refactor: rename /internals to /experimental

- Rename internals.ts to experimental.ts with updated header comment
- Rename docs/content/docs/internals.md to experimental.md with updated content
- Update package.json exports from ./internals to ./experimental
- Update sidebar link from Internals to Experimental
- Rewrite P14 in PHILOSOPHY.md as 'Experimental carries no promise'
- Added promotion criteria: generic (no backend deps), used in 2/3 apps, stable API

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: RitvikSardana

PHILOSOPHY.md

@@ -452,14 +452,23 @@ const isDismissible = computed(() => {
 })
 ```
 
-### P14. Internals carry no promise
+### P14. Experimental carries no promise
 
-**Rule:** Code reached through the `frappe-ui/internals` subpath is private and **exempt from P13**. It can change shape or be removed in any release — including minor/patch — with no deprecation window. Use it from first-party Frappe libraries without expecting stability.
+**Rule:** Code reached through the `frappe-ui/experimental` subpath is private and **exempt from P13**. It can change shape or be removed in any release — including minor/patch — with no deprecation window. Use it from first-party Frappe libraries without expecting stability.
 
-**Why:** First-party libraries need to reuse internal building blocks, composables like `useInputLabeling`, class helpers, headless logic — without every one being promoted to the public API and frozen under P13. `internals` is that escape hatch: the framework gets to consume internals while the *public* surface stays small and the cost of evolving internals stays zero. The alternative, re-exporting each helper from the public API, or opening a `./src/*` wildcard either freezes everything under P13 or exposes everything forever. `internals` is the deliberate middle: a small, curated, explicitly-unstable surface.
+**What lives here:** two kinds of export. (1) *Internal building blocks* — composables, class helpers, and headless logic that frappe-ui's own components share (`useInputLabeling`, `inputFontSizeClasses`, the input-labeling components). (2) *New components* whose shape is still being discovered in real apps. Both are unstable on purpose: an internal because freezing it would freeze the components built on it, a new component because its API hasn't earned a stable contract yet.
+
+**Why:** First-party libraries need to reuse these without every one being promoted to the public API and frozen under P13. `experimental` is that escape hatch: the framework gets to consume and iterate on building blocks and new components while the *public* surface stays small and the cost of evolving them stays zero. The alternative — re-exporting each helper from the public API, or opening a `./src/*` wildcard — either freezes everything under P13 or exposes everything forever. `experimental` is the deliberate middle: a small, curated, explicitly-unstable surface.
 
 **Mechanics:**
-1. Exposed through a single curated barrel (`internals.ts`) behind the `./internals` export **not** a `./src/*` wildcard. Re-export only what a first-party consumer actually needs.
+1. Exposed through a single curated barrel (`experimental.ts`) behind the `./experimental` export **not** a `./src/*` wildcard. Re-export only what a first-party consumer actually needs.
 2. The barrel header restates the no-promise contract at the point of use.
-3. "Private" is by convention, `exports` can't scope visibility to a specific consumer so the contract is the disclaimer, not enforcement. Product/third-party code is told not to import it.
-4. To make an internal stable, deliberately promote it to a public entry point (and thus under P13). Until then, no guarantees.
+3. "Private" is by convention, `exports` can't scope visibility to a specific consumer so the contract is the disclaimer, not enforcement. Product/third-party code is told not to import it; if a product needs one of these and wants stability, it copies the code into its own app rather than depending on this subpath.
+4. To make an experimental export stable, deliberately promote it to a public entry point (and thus under P13). Until then, no guarantees.
+
+**Promotion — moving a component out of `experimental` into the core public API.** A component graduates only when **all** of these hold:
+1. **Generic, not backend-dependent.** It solves a UI problem in the abstract — no coupling to a specific DocType, API shape, or app-specific data model. If it only makes sense inside one product, it stays in that product.
+2. **Proven across apps.** It is actually used in **two or three** of the Frappe apps (Helpdesk, CRM, Gameplan, Drive, …). Real reuse — not anticipated reuse — is the evidence that the abstraction holds.
+3. **Stable API.** Its props, events, slots, and behavior have settled; you no longer expect to reshape them. Promotion is the moment the API freezes under P13, so it must be ready to carry that promise.
+
+Until a component clears all three, it lives in `experimental` and any consumer that needs guarantees keeps its own copy.

docs/components/Docs/sidebarList.ts

@@ -91,7 +91,7 @@ export function getSidebarList(
         { text: 'Icons', link: '/docs/other/icons' },
         { text: 'Utilities', link: '/docs/other/utilities' },
         { text: 'Directives', link: '/docs/other/directives' },
-        { text: 'Internals', link: '/docs/internals' },
+        { text: 'Experimental', link: '/docs/experimental' },
       ],
     },
   ]

docs/content/docs/internals.md docs/content/docs/experimental.mddocs/content/docs/internals.md renamed to docs/content/docs/experimental.md

@@ -1,17 +1,18 @@
-# Internals
+# Experimental
 
-The `frappe-ui/internals` subpath exposes internal building blocks —
-composables, class helpers, components and headless logic — that are not part of the
-public API.
+The `frappe-ui/experimental` subpath exposes internal building blocks and
+new, in-progress components — composables, class helpers, components and
+headless logic — that are not yet part of the stable public API.
 
 Think of it as a staging area: exports live here while their API settles. Over
 time, some of them get promoted to the public API and others get removed.
 
-> **Unstable API** — everything exported from `frappe-ui/internals` is exempt
-> from the usual deprecation policy and can change shape or disappear in _any_
-> release, including minor and patch releases, with no deprecation window.
-> Do **not** import this subpath from product apps or third-party code — pin
-> to a public entry point instead.
+> **Unstable API** — everything exported from `frappe-ui/experimental` is
+> exempt from the usual deprecation policy and can change shape or disappear in
+> _any_ release, including minor and patch releases, with no deprecation
+> window. If you depend on one of these from product or third-party code and
+> need stability, copy it into your own app rather than pinning to this
+> subpath.
 
 ## useInputLabeling
 
@@ -22,7 +23,7 @@ internally, so a custom control built with it gets the same behavior and
 styling hooks for free.
 
 ```ts
-import { useInputLabeling } from 'frappe-ui/internals'
+import { useInputLabeling } from 'frappe-ui/experimental'
 
 const { inputId, labelledBy, describedBy, hasError, errorLines, dataAttrs } =
   useInputLabeling(props, { size: () => props.size })
@@ -43,7 +44,7 @@ import {
   InputError,
   LabelingWrapper,
   useInputLabeling,
-} from 'frappe-ui/internals'
+} from 'frappe-ui/experimental'
 
 const {
   inputId,
@@ -109,7 +110,7 @@ given size token (`'sm' | 'md' | 'lg' | 'xl'`), so custom controls render text
 at the same scale as built-in ones.
 
 ```ts
-import { inputFontSizeClasses } from 'frappe-ui/internals'
+import { inputFontSizeClasses } from 'frappe-ui/experimental'
 
 inputFontSizeClasses('sm') // 'text-base'
 inputFontSizeClasses('lg') // 'text-lg'

internals.ts experimental.tsinternals.ts renamed to experimental.ts

@@ -1,4 +1,4 @@
-// frappe-ui internals — UNSTABLE. No backward-compatibility promise.
+// frappe-ui experimental — UNSTABLE. No backward-compatibility promise.
 
 export { inputFontSizeClasses } from './src/components/Combobox/utils'
 export {

package.json

@@ -45,9 +45,9 @@
       "import": "./src/index.ts",
       "types": "./src/index.ts"
     },
-    "./internals": {
-      "import": "./internals.ts",
-      "types": "./internals.ts"
+    "./experimental": {
+      "import": "./experimental.ts",
+      "types": "./experimental.ts"
     },
     "./frappe": {
       "import": "./frappe/index.js"
@@ -98,7 +98,7 @@
     "vite",
     "icons",
     "tailwind",
-    "internals.ts",
+    "experimental.ts",
     "tsconfig.base.json"
   ],
   "repository": {