@orianatech/pire 0.2.1 → 0.4.0

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

@@ -59,7 +59,7 @@
 .pire-card-body{padding:var(--sp-4);flex:1}
 .pire-card-foot{display:flex;justify-content:flex-end;gap:var(--sp-2);padding:var(--sp-3) var(--sp-4);border-top:1px solid var(--border-subtle)}
 
-/* ---- Field shell (Input, Select, ComboBox) --------------------------- */
+/* ---- Field shell (Input, Select, ComboBox, TextArea, MultiComboBox) --- */
 .pire-field{display:flex;flex-direction:column;gap:var(--sp-1)}
 .pire-field-label{font:var(--type-label);color:var(--text-label)}
 .pire-field-req{color:var(--status-negative-fg);margin-left:var(--sp-0h)}
@@ -90,6 +90,30 @@
 .pire-input::placeholder{color:var(--text-tertiary)}
 .pire-affix{font:var(--type-caption);color:var(--text-secondary);flex:0 0 auto}
 .pire-leading-icon{color:var(--text-tertiary);flex:0 0 auto}
+/* The shell is fixed-height by default because every single-line control is. Controls whose
+   content sets the height (TextArea, MultiComboBox's chips) opt out with data-multiline and
+   keep everything else — focus ring, invalid, disabled, readonly, sizing — from the rules
+   above. This block sits after the [data-size] heights on purpose: equal specificity, so the
+   later `height:auto` wins, and the per-size floor is restored as a min-height. */
+.pire-control[data-multiline="true"]{height:auto;min-height:var(--control-h-md);align-items:stretch;padding-top:var(--sp-2);padding-bottom:var(--sp-2)}
+.pire-control[data-multiline="true"][data-size="sm"]{min-height:var(--control-h-sm)}
+.pire-control[data-multiline="true"][data-size="lg"]{min-height:var(--control-h-lg)}
+
+/* ---- TextArea -------------------------------------------------------- */
+.pire-textarea{display:block;width:100%;resize:vertical;overflow:auto}
+/* autoGrow writes an inline height on every keystroke, so a height dragged by hand would be
+   thrown away on the next one — the grip is removed rather than left lying about it. */
+.pire-textarea[data-auto-grow="true"]{resize:none}
+
+/* ---- MultiComboBox --------------------------------------------------- */
+.pire-chipfield{flex:1;min-width:0;display:flex;flex-wrap:wrap;align-items:center;gap:var(--sp-1)}
+/* Never narrower than a few characters, so the caret stays reachable however many chips are in. */
+.pire-chipinput{flex:1 1 6ch;min-width:6ch}
+/* Each chip's remove button is a Tab stop of its own inside the shell, and the shell's blanket
+   `:focus-visible{outline:none}` (see above) would otherwise leave it unmarked. */
+.pire-chipfield .pire-tag-remove[data-focus-visible]{outline:var(--focus-w) solid var(--focus-color);outline-offset:var(--focus-offset)}
+/* One ring at a time: while a chip owns focus it, not the shell, is what moved. */
+.pire-control:has(.pire-tag-remove[data-focus-visible])[data-focus-within]{outline:none}
 
 /* ---- Select / ListBox popover ---------------------------------------- */
 .pire-select-value{flex:1;min-width:0;text-align:left;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;font:var(--type-body)}
@@ -164,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 -------------------------------------------------------- */
@@ -203,6 +249,28 @@
 .pire-progress[data-status="negative"] .pire-progress-fill{background:var(--status-negative-fg)}
 .pire-tooltip{max-width:240px;padding:var(--sp-1) var(--sp-2);border-radius:var(--radius-1);background:var(--gray-90);color:var(--text-inverse);font:var(--type-caption);box-shadow:var(--shadow-2);animation:pire-fade-in var(--dur-fast) var(--ease-entrance)}
 
+/* ---- Skeleton ---------------------------------------------------------- */
+/* The sweep is a lightness *difference* between two surface aliases, not a fixed direction:
+   --surface-hover is lighter than --surface-active in the light theme and darker in the dark
+   one, and either reads as a sweep. That keeps the placeholder on the shared alias layer
+   instead of introducing a skeleton-only token pair for both themes to maintain.
+   The duration is derived, not literal: a shimmer at --dur-slow (400ms) is agitated rather
+   than patient, and 3x is the slowest step the motion scale can express. */
+.pire-skeleton{display:block;width:100%;background-color:var(--surface-active);background-image:linear-gradient(90deg,transparent,var(--surface-hover),transparent);background-size:200% 100%;background-repeat:no-repeat;border-radius:var(--radius-1);animation:pire-skeleton-sweep calc(var(--dur-slow) * 3) var(--ease-standard) infinite}
+.pire-skeleton[data-shape="text"]{height:var(--fs-body)}
+.pire-skeleton[data-shape="block"]{height:var(--sp-16);border-radius:var(--radius-2)}
+.pire-skeleton[data-shape="circle"]{width:var(--sp-8);height:var(--sp-8);border-radius:var(--radius-pill);flex:0 0 auto}
+@keyframes pire-skeleton-sweep{from{background-position:150% 0}to{background-position:-50% 0}}
+/* Geometry copied from .pire-tr / .pire-td, not approximated, so a loading table and a loaded
+   one are the same height and the rows do not jump when the data lands. */
+.pire-skeleton-row{display:flex;align-items:center;height:var(--row-h-regular);border-bottom:1px solid var(--border-subtle)}
+.pire-skeleton-row[data-density="condensed"]{height:var(--row-h-condensed)}
+.pire-skeleton-row[data-density="comfortable"]{height:var(--row-h-comfortable)}
+.pire-skeleton-cell{flex:1 1 0;min-width:0;display:flex;padding:0 var(--sp-3)}
+.pire-skeleton-row[data-density="condensed"] .pire-skeleton-cell{padding:0 var(--sp-2)}
+.pire-skeleton-cell[data-align="right"]{justify-content:flex-end}
+.pire-skeleton-cell[data-align="center"]{justify-content:center}
+
 /* ---- Data ------------------------------------------------------------ */
 .pire-table-wrap{overflow:auto;background:var(--surface-card);border:1px solid var(--border-subtle);border-radius:var(--radius-2)}
 .pire-table{width:100%;border-collapse:collapse;font:var(--type-body)}
@@ -348,6 +416,10 @@
 
 /* ---- Reduced motion --------------------------------------------------- */
 @media (prefers-reduced-motion: reduce){.pire-modal,.pire-toast,.pire-popover,.pire-tooltip,.pire-sidepanel{animation:none}
+/* The skeleton also drops its background sweep, not just the animation: an infinite shimmer is
+   exactly the "large, repeated motion" the preference is asking us to stop, and the placeholder
+   still reads from its shape and surface contrast alone. */
+.pire-skeleton{animation:none;background-image:none}
 /* !important is the point here: this must beat every component transition, including any a
    consuming app has layered on top. Honouring the OS motion preference outranks the style rule. */
 /* biome-ignore lint/complexity/noImportantStyles: accessibility override must win unconditionally */