@orianatech/pire 0.3.0 → 0.4.0

package/README.md

@@ -10,7 +10,8 @@ Requires Node 20+ and pnpm.
 ```bash
 pnpm install
 pnpm storybook        # docs + playground at http://localhost:6006
-pnpm build            # dist/ (ESM + CJS + .d.ts + CSS)
+pnpm build            # dist/ (ESM + CJS + .d.ts + CSS), icon codegen first
+pnpm icons:generate   # re-inline the Carbon glyphs listed in icon-map.ts
 pnpm typecheck        # tsc --noEmit
 pnpm lint             # biome
 ```
@@ -76,14 +77,45 @@ Override tokens, never component rules:
 
 ### Icons
 
-Names are Lucide slugs; the shipped pack is IBM Carbon, resolved through an internal map. Glyphs
-load from a CDN by default — self-host in production:
+**Zero configuration, and no network.** Every glyph is inlined into the bundle at build time and
+rendered as inline SVG, so icons paint offline, cost no requests, and report nothing to anyone.
+
+```tsx
+<Icon name="shopping-cart" size={20} />              {/* decorative: aria-hidden */}
+<Icon name="lock" size={20} label="Locked record" /> {/* meaningful: role="img" + aria-label */}
+```
+
+Names are canonical **Lucide slugs**; the shipped pack is IBM Carbon, reached through an internal
+map, so a pack swap never touches a call site. The same names are what the `icon` prop on `Button`,
+`IconButton`, `Card`, `KpiTile`, `Tabs`, `EmptyState` and `InlineMessage` takes.
+
+Glyphs are filled with `currentColor`, so an icon takes the colour of the text it sits in — style the
+container, not the icon. `size` is the pixel box: 16 in dense UI, 20 in headers, 24 in tiles.
+
+An unrecognised name renders an empty box of the right size and logs one `[pire]` console warning
+naming it. The warning is compiled out of production builds.
+
+The bundled set covers what the ERP screens use. For anything else, register the *inner* markup of a
+32×32 SVG once at startup:
 
 ```ts
 import { configureIcons } from '@orianatech/pire';
-configureIcons({ base: '/assets/icons/' });   // folder of <slug>.svg
+
+configureIcons({
+  resolve: (name) => (name === 'oriana-mark' ? '<circle cx="16" cy="16" r="8"/>' : undefined),
+});
 ```
 
+> **Upgrading from 0.3 or earlier.** Glyphs used to be fetched per render from `cdn.jsdelivr.net`,
+> which meant blank icons in an offline PWA, so apps self-hosted the SVGs and called
+> `configureIcons({ base })`. That is now unnecessary: **delete the `configureIcons({ base })` call
+> and the vendored `<slug>.svg` files.** `base` and `pack` are still accepted so existing code keeps
+> compiling, but they are ignored and warn in development. The `lucide` pack is gone —
+> `pack="lucide"` now renders the Carbon glyph.
+
+Adding a glyph to the library itself is one line in `src/components/core/icon-map.ts` plus a build;
+see the Icons section of `CLAUDE.md`.
+
 ## Migrating from the HTML/JSX prototypes
 
 | Prototype API | Package API |
@@ -104,7 +136,13 @@ configureIcons({ base: '/assets/icons/' });   // folder of <slug>.svg
 
 ## Toolchain notes
 
-- `pnpm build` runs `tsup` for the JS bundles, then `tsc -p tsconfig.build.json` for the
+- `pnpm build` first runs `scripts/generate-icon-data.mjs`, which inlines the Carbon SVGs listed in
+  `src/components/core/icon-map.ts` into a committed `icon-data.generated.ts`. `@carbon/icons` is a
+  **devDependency on purpose** — it depends on `@ibm/telemetry-js` and runs `ibmtelemetry` from a
+  `postinstall` script, which as a runtime dependency would execute in every app that installs Pire.
+  The generated file is committed because typecheck, lint, tests and Storybook all read `src/`
+  without building; its install script is denied in `pnpm-workspace.yaml`.
+- `pnpm build` then runs `tsup` for the JS bundles, then `tsc -p tsconfig.build.json` for the
   `.d.ts` files, then `scripts/postbuild-types.mjs`. tsup's own declaration pipeline is not
   compatible with the TypeScript 7 native compiler, so `dts` is off in `tsup.config.ts` —
   leave it that way. The post-pass makes the emitted declarations resolvable under

package/dist/components/core/Icon.d.cts

@@ -1,22 +1,37 @@
-import * as React from 'react';
+import type * as React from 'react';
+/** @deprecated Retained only so existing `pack` values still typecheck. Glyphs are bundled from
+ *  the Carbon pack; there is no second pack and no remote fetch, so the value is ignored. */
 export type IconPack = 'carbon' | 'lucide';
 export interface IconConfig {
-    /** Pack used when an <Icon> does not specify one. Default 'carbon'. */
+    /** @deprecated Ignored. The bundled Carbon pack is the only pack — `lucide` was a remote-URL
+     *  pack and no longer exists. Setting this warns in development. */
     pack?: IconPack;
-    /** Serve glyphs from your own origin: a folder of <slug>.svg files. Recommended in production. */
+    /** @deprecated Ignored — glyphs are inlined in the bundle, so there is nothing to serve from a
+     *  folder. Apps that vendored `<slug>.svg` files into `public/` to survive offline can delete
+     *  both the files and this call. Setting it warns in development. */
     base?: string;
+    /** Escape hatch for a glyph Pire does not bundle, or to override one. Return the *inner* markup
+     *  of a 32x32 SVG (`'<path d="…"/>'`), or `undefined` to fall through to the bundled set. The
+     *  string is injected as-is, so it must be authored markup, never user input. */
+    resolve?: (name: string) => string | undefined;
 }
-/** Point the whole app at a self-hosted glyph folder, or switch packs, once at startup. */
+/** Optional. The bundled Carbon set needs no configuration — this exists only to register glyphs
+ *  Pire does not ship, once at startup. */
 export declare function configureIcons(next: IconConfig): void;
 export interface IconProps extends Omit<React.HTMLAttributes<HTMLSpanElement>, 'children'> {
-    /** Canonical (Lucide) slug, e.g. "shopping-cart". Mapped automatically for the Carbon pack. */
+    /** Canonical (Lucide) slug, e.g. "shopping-cart". Translated to the Carbon pack automatically. */
     name: string;
     /** Pixel box. 16 in dense UI, 20 in headers, 24 in tiles. */
     size?: number;
     /** Accessible name. Omit for decorative icons — they are hidden from assistive tech. */
     label?: string;
+    /** @deprecated Ignored. See {@link IconConfig.pack}. */
     pack?: IconPack;
 }
-/** Glyph painted as a CSS mask over currentColor, so it inherits text colour everywhere.
- *  A missing glyph degrades to empty space rather than a solid block. */
+/** Glyph rendered as inline SVG filled with `currentColor`, so it inherits text colour everywhere
+ *  and paints with no network at all — which the previous CDN-backed implementation did not, leaving
+ *  every icon blank offline in the PWAs that consume this library.
+ *
+ *  An unknown name still renders nothing, so a typo cannot collapse a layout, but it warns in
+ *  development: the silent blank gap was the failure mode worth killing. */
 export declare function Icon({ name, size, label, pack, style, ...rest }: IconProps): React.JSX.Element;

package/dist/components/core/Icon.d.ts

@@ -1,23 +1,38 @@
-import * as React from 'react';
+import type * as React from 'react';
+/** @deprecated Retained only so existing `pack` values still typecheck. Glyphs are bundled from
+ *  the Carbon pack; there is no second pack and no remote fetch, so the value is ignored. */
 export type IconPack = 'carbon' | 'lucide';
 export interface IconConfig {
-    /** Pack used when an <Icon> does not specify one. Default 'carbon'. */
+    /** @deprecated Ignored. The bundled Carbon pack is the only pack — `lucide` was a remote-URL
+     *  pack and no longer exists. Setting this warns in development. */
     pack?: IconPack;
-    /** Serve glyphs from your own origin: a folder of <slug>.svg files. Recommended in production. */
+    /** @deprecated Ignored — glyphs are inlined in the bundle, so there is nothing to serve from a
+     *  folder. Apps that vendored `<slug>.svg` files into `public/` to survive offline can delete
+     *  both the files and this call. Setting it warns in development. */
     base?: string;
+    /** Escape hatch for a glyph Pire does not bundle, or to override one. Return the *inner* markup
+     *  of a 32x32 SVG (`'<path d="…"/>'`), or `undefined` to fall through to the bundled set. The
+     *  string is injected as-is, so it must be authored markup, never user input. */
+    resolve?: (name: string) => string | undefined;
 }
-/** Point the whole app at a self-hosted glyph folder, or switch packs, once at startup. */
+/** Optional. The bundled Carbon set needs no configuration — this exists only to register glyphs
+ *  Pire does not ship, once at startup. */
 export declare function configureIcons(next: IconConfig): void;
 export interface IconProps extends Omit<React.HTMLAttributes<HTMLSpanElement>, 'children'> {
-    /** Canonical (Lucide) slug, e.g. "shopping-cart". Mapped automatically for the Carbon pack. */
+    /** Canonical (Lucide) slug, e.g. "shopping-cart". Translated to the Carbon pack automatically. */
     name: string;
     /** Pixel box. 16 in dense UI, 20 in headers, 24 in tiles. */
     size?: number;
     /** Accessible name. Omit for decorative icons — they are hidden from assistive tech. */
     label?: string;
+    /** @deprecated Ignored. See {@link IconConfig.pack}. */
     pack?: IconPack;
 }
-/** Glyph painted as a CSS mask over currentColor, so it inherits text colour everywhere.
- *  A missing glyph degrades to empty space rather than a solid block. */
+/** Glyph rendered as inline SVG filled with `currentColor`, so it inherits text colour everywhere
+ *  and paints with no network at all — which the previous CDN-backed implementation did not, leaving
+ *  every icon blank offline in the PWAs that consume this library.
+ *
+ *  An unknown name still renders nothing, so a typo cannot collapse a layout, but it warns in
+ *  development: the silent blank gap was the failure mode worth killing. */
 export declare function Icon({ name, size, label, pack, style, ...rest }: IconProps): React.JSX.Element;
 //# sourceMappingURL=Icon.d.ts.map

package/dist/components/core/Icon.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Icon.d.ts","sourceRoot":"","sources":["../../../src/components/core/Icon.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,MAAM,MAAM,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;AA4B3C,MAAM,WAAW,UAAU;IACzB,uEAAuE;IACvE,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB,kGAAkG;IAClG,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,2FAA2F;AAC3F,wBAAgB,cAAc,CAAC,IAAI,EAAE,UAAU,QAAsC;AAErF,MAAM,WAAW,SAAU,SAAQ,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,eAAe,CAAC,EAAE,UAAU,CAAC;IACxF,+FAA+F;IAC/F,IAAI,EAAE,MAAM,CAAC;IACb,6DAA6D;IAC7D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wFAAwF;IACxF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,QAAQ,CAAC;CACjB;AAED;yEACyE;AACzE,wBAAgB,IAAI,CAAC,EAAE,IAAI,EAAE,IAAS,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,IAAI,EAAE,EAAE,SAAS,qBAuB/E"}
+{"version":3,"file":"Icon.d.ts","sourceRoot":"","sources":["../../../src/components/core/Icon.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,KAAK,MAAM,OAAO,CAAC;AA2BpC;6FAC6F;AAC7F,MAAM,MAAM,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAE3C,MAAM,WAAW,UAAU;IACzB;wEACoE;IACpE,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB;;yEAEqE;IACrE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;qFAEiF;IACjF,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;CAChD;AAID;2CAC2C;AAC3C,wBAAgB,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI,CAerD;AAED,MAAM,WAAW,SAAU,SAAQ,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,eAAe,CAAC,EAAE,UAAU,CAAC;IACxF,kGAAkG;IAClG,IAAI,EAAE,MAAM,CAAC;IACb,6DAA6D;IAC7D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wFAAwF;IACxF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wDAAwD;IACxD,IAAI,CAAC,EAAE,QAAQ,CAAC;CACjB;AAED;;;;;4EAK4E;AAC5E,wBAAgB,IAAI,CAAC,EAAE,IAAI,EAAE,IAAS,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,IAAI,EAAE,EAAE,SAAS,qBAqC/E"}

package/dist/components/core/icon-data.generated.d.cts

@@ -0,0 +1 @@
+export declare const ICON_MARKUP: Record<string, string>;

package/dist/components/core/icon-data.generated.d.ts

@@ -0,0 +1,2 @@
+export declare const ICON_MARKUP: Record<string, string>;
+//# sourceMappingURL=icon-data.generated.d.ts.map

package/dist/components/core/icon-data.generated.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"icon-data.generated.d.ts","sourceRoot":"","sources":["../../../src/components/core/icon-data.generated.ts"],"names":[],"mappings":"AAQA,eAAO,MAAM,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAgE9C,CAAC"}

package/dist/components/core/icon-map.d.cts

@@ -0,0 +1,13 @@
+/** Canonical Pire icon names are Lucide slugs; the shipped IBM Carbon pack is reached through
+ *  this map, so swapping packs never touches a call site. A new icon name used by a component
+ *  must be added here — that is the whole registration step.
+ *
+ *  This file is also the single source of truth for *which glyphs get vendored*:
+ *  `scripts/generate-icon-data.mjs` reads it and inlines the matching SVG from
+ *  `@carbon/icons` into `icon-data.generated.ts`. The script cannot import TypeScript, so it
+ *  parses this object textually. **Every entry must stay a literal `'name': 'slug',` pair.**
+ *  A spread, a computed key or a template literal is invisible to the generator: the glyph
+ *  never gets vendored and `Icon` warns at runtime instead of rendering. Multiple names may
+ *  point at one slug (`boxes` and `package` both mean `box`); the generator de-duplicates.
+ */
+export declare const CARBON_MAP: Record<string, string>;

package/dist/components/core/icon-map.d.ts

@@ -0,0 +1,14 @@
+/** Canonical Pire icon names are Lucide slugs; the shipped IBM Carbon pack is reached through
+ *  this map, so swapping packs never touches a call site. A new icon name used by a component
+ *  must be added here — that is the whole registration step.
+ *
+ *  This file is also the single source of truth for *which glyphs get vendored*:
+ *  `scripts/generate-icon-data.mjs` reads it and inlines the matching SVG from
+ *  `@carbon/icons` into `icon-data.generated.ts`. The script cannot import TypeScript, so it
+ *  parses this object textually. **Every entry must stay a literal `'name': 'slug',` pair.**
+ *  A spread, a computed key or a template literal is invisible to the generator: the glyph
+ *  never gets vendored and `Icon` warns at runtime instead of rendering. Multiple names may
+ *  point at one slug (`boxes` and `package` both mean `box`); the generator de-duplicates.
+ */
+export declare const CARBON_MAP: Record<string, string>;
+//# sourceMappingURL=icon-map.d.ts.map

package/dist/components/core/icon-map.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"icon-map.d.ts","sourceRoot":"","sources":["../../../src/components/core/icon-map.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAiB7C,CAAC"}

package/dist/components/navigation/ShellBar.d.cts

@@ -8,10 +8,17 @@ export interface ShellBarProps extends Omit<React.HTMLAttributes<HTMLElement>, '
     title?: React.ReactNode;
     onMenu?: () => void;
     onSearch?: () => void;
+    /** Accessible name for the menu button. Defaults to English, and the bar has no access to the app's
+     *  catalogue — a Spanish product must pass its own or ship an English screen-reader label. */
+    menuLabel?: string;
+    /** Accessible name for the search button, for the same reason as {@link ShellBarProps.menuLabel}.
+     *  Until this existed the only way to localise it was to drop `onSearch` and re-render the icon by
+     *  hand, which is how a shell ends up with two search icons. */
+    searchLabel?: string;
     /** IconButtons with variant="inverse". */
     actions?: React.ReactNode;
     /** Full name — initials render into the avatar. */
     user?: string;
 }
 /** Fixed 48px application chrome. One per page, always the first landmark. */
-export declare function ShellBar({ product, monogram, title, onMenu, onSearch, actions, user, className, ...rest }: ShellBarProps): React.JSX.Element;
+export declare function ShellBar({ product, monogram, title, onMenu, onSearch, menuLabel, searchLabel, actions, user, className, ...rest }: ShellBarProps): React.JSX.Element;

package/dist/components/navigation/ShellBar.d.ts

@@ -8,11 +8,18 @@ export interface ShellBarProps extends Omit<React.HTMLAttributes<HTMLElement>, '
     title?: React.ReactNode;
     onMenu?: () => void;
     onSearch?: () => void;
+    /** Accessible name for the menu button. Defaults to English, and the bar has no access to the app's
+     *  catalogue — a Spanish product must pass its own or ship an English screen-reader label. */
+    menuLabel?: string;
+    /** Accessible name for the search button, for the same reason as {@link ShellBarProps.menuLabel}.
+     *  Until this existed the only way to localise it was to drop `onSearch` and re-render the icon by
+     *  hand, which is how a shell ends up with two search icons. */
+    searchLabel?: string;
     /** IconButtons with variant="inverse". */
     actions?: React.ReactNode;
     /** Full name — initials render into the avatar. */
     user?: string;
 }
 /** Fixed 48px application chrome. One per page, always the first landmark. */
-export declare function ShellBar({ product, monogram, title, onMenu, onSearch, actions, user, className, ...rest }: ShellBarProps): React.JSX.Element;
+export declare function ShellBar({ product, monogram, title, onMenu, onSearch, menuLabel, searchLabel, actions, user, className, ...rest }: ShellBarProps): React.JSX.Element;
 //# sourceMappingURL=ShellBar.d.ts.map

package/dist/components/navigation/ShellBar.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ShellBar.d.ts","sourceRoot":"","sources":["../../../src/components/navigation/ShellBar.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,KAAK,MAAM,OAAO,CAAC;AAIpC,MAAM,WAAW,aAAc,SAAQ,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IACrF,kDAAkD;IAClD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mFAAmF;IACnF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mCAAmC;IACnC,KAAK,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC;IACtB,0CAA0C;IAC1C,OAAO,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAC1B,mDAAmD;IACnD,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAID,8EAA8E;AAC9E,wBAAgB,QAAQ,CAAC,EAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,GAAG,IAAI,EAAE,EAAE,aAAa,qBAaxH"}
+{"version":3,"file":"ShellBar.d.ts","sourceRoot":"","sources":["../../../src/components/navigation/ShellBar.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,KAAK,MAAM,OAAO,CAAC;AAIpC,MAAM,WAAW,aAAc,SAAQ,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IACrF,kDAAkD;IAClD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mFAAmF;IACnF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mCAAmC;IACnC,KAAK,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC;IACtB;kGAC8F;IAC9F,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;oEAEgE;IAChE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0CAA0C;IAC1C,OAAO,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAC1B,mDAAmD;IACnD,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAID,8EAA8E;AAC9E,wBAAgB,QAAQ,CAAC,EAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,SAA6B,EAClG,WAAsB,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,GAAG,IAAI,EAAE,EAAE,aAAa,qBAa3E"}

package/dist/components/navigation/SideNav.d.cts

@@ -1,9 +1,24 @@
-import type * as React from 'react';
+import * as React from 'react';
+/** A second-level destination, nested under a first-level entry.
+ *
+ *  Deliberately has no `icon`: only the first level carries one, so the second level reads as an
+ *  indented list of labels under a single glyph rather than a wall of decoration. Leaving `icon` off
+ *  the *type* is what stops that drifting back in one call site at a time. */
+export interface SideNavChildItem {
+    id: string;
+    label: string;
+    count?: number;
+}
 export interface SideNavItem {
     id: string;
     label: string;
     icon?: string;
     count?: number;
+    /** Second-level destinations. Supplying this turns the entry into a collapsible group: it stops
+     *  being a destination itself (pressing it expands, never navigates) and `id` becomes the
+     *  expansion key used by `expandedIds` / `defaultExpandedIds`, not something `onChange` can ever
+     *  emit. Omit it and the entry behaves exactly as it always has. */
+    items?: SideNavChildItem[];
 }
 export interface SideNavGroup {
     label?: string;
@@ -13,10 +28,47 @@ export interface SideNavProps extends Omit<React.HTMLAttributes<HTMLElement>, 'o
     /** Spaces-and-pages hierarchy: one group per space. */
     groups: SideNavGroup[];
     value?: string;
-    /** Fires with the selected item id — not a DOM change event. */
+    /** Fires with the selected item id — not a DOM change event. Only ever a destination id: a
+     *  first-level entry that owns `items` is a disclosure, and toggling it does not fire this. */
     onChange?: (id: string) => void;
-    /** 48px icon rail. Labels move into tooltips. */
+    /** Expanded first-level entry ids — the controlled half of the pair. Pass it and you own expansion
+     *  outright, including expanding the group that holds `value`. */
+    expandedIds?: string[];
+    /** Initial expanded ids for the uncontrolled case. Omit it and the group holding `value` opens
+     *  itself; supply it and it is taken literally, so `value`'s group can start closed if that is
+     *  genuinely what you want. */
+    defaultExpandedIds?: string[];
+    /** Fires with every expanded id after a toggle, controlled or not. */
+    onExpandedChange?: (ids: string[]) => void;
+    /** 48px icon rail. Labels move into tooltips, and second-level items are not rendered at all —
+     *  see the note on {@link SideNav}. */
     collapsed?: boolean;
     footer?: React.ReactNode;
 }
-export declare function SideNav({ groups, value, onChange, collapsed, footer, className, ...rest }: SideNavProps): React.JSX.Element;
+/** Primary navigation. A first-level entry is either a destination (icon + label, selectable) or a
+ *  collapsible group (icon + label + chevron) when it carries `items` — the two coexist in one list,
+ *  which is how a 35-destination ERP menu fits without showing all 35 at once.
+ *
+ *  Both levels are plain `Button`s and the disclosure is React Aria's `Disclosure` /
+ *  `DisclosureGroup`, so `aria-expanded`, `aria-controls`, the panel's `role="group"` and
+ *  `aria-labelledby`, and Enter/Space on the trigger all come from React Aria rather than from
+ *  hand-rolled ARIA here.
+ *
+ *  Three things worth knowing before you use it:
+ *
+ *  - **The panel is always in the DOM.** React Aria hides a collapsed panel with
+ *    `hidden="until-found"`, applied imperatively in a layout effect, so find-in-page can reveal it.
+ *    A test asserting a collapsed child is *absent* will fail; assert `aria-expanded` on the trigger,
+ *    or visibility, instead. The corollary in CSS: any `display` we set on the panel would beat the
+ *    UA's `[hidden] { display: none }`, leaving collapsed children focusable under
+ *    `aria-hidden="true"`. `.pire-sidenav-subnav[hidden]` in `components.css` is that guard.
+ *  - **`collapsed` and expansion are different axes, and the rail wins.** With `collapsed` set there
+ *    are no labels, and a second level is nothing *but* labels, so children are not rendered in the
+ *    rail. A group's row becomes an ordinary icon button that records the expansion (so the group is
+ *    already open when the rail expands) and lights up while it holds `value`, which is the one thing
+ *    a rail must still communicate. It follows that a nav with collapsible groups needs a way back
+ *    out of the rail — `ShellBar`'s `onMenu` — or 25 of those 35 destinations are unreachable, for
+ *    everyone, exactly as the labels already are.
+ *  - **Several groups can be open at once**, and there is no accordion mode. Closing the group you
+ *    are in to open another is the wrong trade in a nav whose whole job is showing where you are. */
+export declare function SideNav({ groups, value, onChange, expandedIds, defaultExpandedIds, onExpandedChange, collapsed, footer, className, ...rest }: SideNavProps): React.JSX.Element;

package/dist/components/navigation/SideNav.d.ts

@@ -1,9 +1,24 @@
-import type * as React from 'react';
+import * as React from 'react';
+/** A second-level destination, nested under a first-level entry.
+ *
+ *  Deliberately has no `icon`: only the first level carries one, so the second level reads as an
+ *  indented list of labels under a single glyph rather than a wall of decoration. Leaving `icon` off
+ *  the *type* is what stops that drifting back in one call site at a time. */
+export interface SideNavChildItem {
+    id: string;
+    label: string;
+    count?: number;
+}
 export interface SideNavItem {
     id: string;
     label: string;
     icon?: string;
     count?: number;
+    /** Second-level destinations. Supplying this turns the entry into a collapsible group: it stops
+     *  being a destination itself (pressing it expands, never navigates) and `id` becomes the
+     *  expansion key used by `expandedIds` / `defaultExpandedIds`, not something `onChange` can ever
+     *  emit. Omit it and the entry behaves exactly as it always has. */
+    items?: SideNavChildItem[];
 }
 export interface SideNavGroup {
     label?: string;
@@ -13,11 +28,48 @@ export interface SideNavProps extends Omit<React.HTMLAttributes<HTMLElement>, 'o
     /** Spaces-and-pages hierarchy: one group per space. */
     groups: SideNavGroup[];
     value?: string;
-    /** Fires with the selected item id — not a DOM change event. */
+    /** Fires with the selected item id — not a DOM change event. Only ever a destination id: a
+     *  first-level entry that owns `items` is a disclosure, and toggling it does not fire this. */
     onChange?: (id: string) => void;
-    /** 48px icon rail. Labels move into tooltips. */
+    /** Expanded first-level entry ids — the controlled half of the pair. Pass it and you own expansion
+     *  outright, including expanding the group that holds `value`. */
+    expandedIds?: string[];
+    /** Initial expanded ids for the uncontrolled case. Omit it and the group holding `value` opens
+     *  itself; supply it and it is taken literally, so `value`'s group can start closed if that is
+     *  genuinely what you want. */
+    defaultExpandedIds?: string[];
+    /** Fires with every expanded id after a toggle, controlled or not. */
+    onExpandedChange?: (ids: string[]) => void;
+    /** 48px icon rail. Labels move into tooltips, and second-level items are not rendered at all —
+     *  see the note on {@link SideNav}. */
     collapsed?: boolean;
     footer?: React.ReactNode;
 }
-export declare function SideNav({ groups, value, onChange, collapsed, footer, className, ...rest }: SideNavProps): React.JSX.Element;
+/** Primary navigation. A first-level entry is either a destination (icon + label, selectable) or a
+ *  collapsible group (icon + label + chevron) when it carries `items` — the two coexist in one list,
+ *  which is how a 35-destination ERP menu fits without showing all 35 at once.
+ *
+ *  Both levels are plain `Button`s and the disclosure is React Aria's `Disclosure` /
+ *  `DisclosureGroup`, so `aria-expanded`, `aria-controls`, the panel's `role="group"` and
+ *  `aria-labelledby`, and Enter/Space on the trigger all come from React Aria rather than from
+ *  hand-rolled ARIA here.
+ *
+ *  Three things worth knowing before you use it:
+ *
+ *  - **The panel is always in the DOM.** React Aria hides a collapsed panel with
+ *    `hidden="until-found"`, applied imperatively in a layout effect, so find-in-page can reveal it.
+ *    A test asserting a collapsed child is *absent* will fail; assert `aria-expanded` on the trigger,
+ *    or visibility, instead. The corollary in CSS: any `display` we set on the panel would beat the
+ *    UA's `[hidden] { display: none }`, leaving collapsed children focusable under
+ *    `aria-hidden="true"`. `.pire-sidenav-subnav[hidden]` in `components.css` is that guard.
+ *  - **`collapsed` and expansion are different axes, and the rail wins.** With `collapsed` set there
+ *    are no labels, and a second level is nothing *but* labels, so children are not rendered in the
+ *    rail. A group's row becomes an ordinary icon button that records the expansion (so the group is
+ *    already open when the rail expands) and lights up while it holds `value`, which is the one thing
+ *    a rail must still communicate. It follows that a nav with collapsible groups needs a way back
+ *    out of the rail — `ShellBar`'s `onMenu` — or 25 of those 35 destinations are unreachable, for
+ *    everyone, exactly as the labels already are.
+ *  - **Several groups can be open at once**, and there is no accordion mode. Closing the group you
+ *    are in to open another is the wrong trade in a nav whose whole job is showing where you are. */
+export declare function SideNav({ groups, value, onChange, expandedIds, defaultExpandedIds, onExpandedChange, collapsed, footer, className, ...rest }: SideNavProps): React.JSX.Element;
 //# sourceMappingURL=SideNav.d.ts.map

package/dist/components/navigation/SideNav.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SideNav.d.ts","sourceRoot":"","sources":["../../../src/components/navigation/SideNav.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,KAAK,MAAM,OAAO,CAAC;AAMpC,MAAM,WAAW,WAAW;IAAG,EAAE,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE;AACzF,MAAM,WAAW,YAAY;IAAG,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,WAAW,EAAE,CAAA;CAAE;AAEtE,MAAM,WAAW,YAAa,SAAQ,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,WAAW,CAAC,EAAE,UAAU,CAAC;IACvF,uDAAuD;IACvD,MAAM,EAAE,YAAY,EAAE,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gEAAgE;IAChE,QAAQ,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,iDAAiD;IACjD,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,MAAM,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;CAC1B;AAED,wBAAgB,OAAO,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,IAAI,EAAE,EAAE,YAAY,qBAwBvG"}
+{"version":3,"file":"SideNav.d.ts","sourceRoot":"","sources":["../../../src/components/navigation/SideNav.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAO/B;;;;8EAI8E;AAC9E,MAAM,WAAW,gBAAgB;IAAG,EAAE,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE;AAE/E,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;wEAGoE;IACpE,KAAK,CAAC,EAAE,gBAAgB,EAAE,CAAC;CAC5B;AAED,MAAM,WAAW,YAAY;IAAG,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,WAAW,EAAE,CAAA;CAAE;AAEtE,MAAM,WAAW,YAAa,SAAQ,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,WAAW,CAAC,EAAE,UAAU,CAAC;IACvF,uDAAuD;IACvD,MAAM,EAAE,YAAY,EAAE,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;mGAC+F;IAC/F,QAAQ,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC;sEACkE;IAClE,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB;;mCAE+B;IAC/B,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC9B,sEAAsE;IACtE,gBAAgB,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,IAAI,CAAC;IAC3C;2CACuC;IACvC,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,MAAM,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;CAC1B;AAaD;;;;;;;;;;;;;;;;;;;;;;;;;qGAyBqG;AACrG,wBAAgB,OAAO,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,kBAAkB,EAAE,gBAAgB,EAClG,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,IAAI,EAAE,EAAE,YAAY,qBAwGtD"}

package/dist/components.css

@@ -188,6 +188,28 @@
 .pire-sidenav-item[data-hovered]{background:var(--surface-hover)}
 .pire-sidenav-item[data-selected="true"]{background:var(--surface-selected);border-left-color:var(--accent-bg);color:var(--accent-subtle-fg);font:var(--type-body-strong)}
 .pire-sidenav-count{margin-left:auto;font:var(--type-code);color:var(--text-tertiary)}
+/* Second level. `-tree` is React Aria's DisclosureGroup, `-section` one Disclosure; both exist only
+   to keep the rows in a column, since the wrappers are divs the component cannot avoid. */
+.pire-sidenav-tree,.pire-sidenav-section{display:flex;flex-direction:column}
+/* The trailing chevron. Its own auto margin pushes it to the edge on a group row with no count; when
+   there is a count, the count's auto margin has already claimed the free space and a second auto here
+   would split it and leave the count floating mid-row — hence the reset. */
+.pire-sidenav-chevron{margin-left:auto;color:var(--text-tertiary);transition:transform var(--dur-fast) var(--ease-standard)}
+.pire-sidenav-count + .pire-sidenav-chevron{margin-left:0}
+.pire-sidenav-section:not([data-expanded]) .pire-sidenav-chevron{transform:rotate(-90deg)}
+/* Marks a group row whose child is the current destination: the accent tick and label weight of a
+   selection without its fill, so the trail to `aria-current` reads at a glance and still loses to it.
+   Also the only cue left in the icon rail, where the children are not rendered. */
+.pire-sidenav-item[data-active-child="true"]{border-left-color:var(--accent-bg);color:var(--accent-subtle-fg);font:var(--type-body-strong)}
+/* React Aria animates the panel through --disclosure-panel-height, and applies `hidden` only once the
+   animation settles. The `display` above therefore has to be undone for the collapsed state: it beats
+   the UA's `[hidden]{display:none}`, and a visible-to-the-layout panel under `aria-hidden="true"`
+   leaves every child in the tab order — an aria-hidden-focus defect, not just a cosmetic one. */
+.pire-sidenav-subnav{display:flex;flex-direction:column;overflow:hidden;height:var(--disclosure-panel-height,auto);transition:height var(--dur-fast) var(--ease-standard)}
+.pire-sidenav-subnav[hidden]{display:none}
+/* Indented to the parent's *label*, not its icon: page padding + the 16px glyph box + the row gap.
+   Condensed height because a two-level menu is 35 rows, not 10. */
+.pire-sidenav-subitem{height:var(--row-h-condensed);padding-left:calc(var(--sp-4) + var(--sp-4) + var(--sp-3))}
 .pire-sidenav-footer{margin-top:auto;padding:var(--sp-3) var(--sp-4);border-top:1px solid var(--border-subtle)}
 
 /* ---- Feedback -------------------------------------------------------- */