@apliteni/apliteni-ui 0.11.4 → 0.23.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apliteni/apliteni-ui",
-  "version": "0.11.4",
+  "version": "0.23.1",
   "workspaces": [
     "react"
   ],

package/react/dist/index.css

@@ -1,3 +1,22 @@
+/* ../src/styles/reduced-motion.css */
+@media (prefers-reduced-motion: reduce) {
+  html {
+    scroll-behavior: auto !important;
+  }
+  *,
+  ::before,
+  ::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+    scroll-behavior: auto !important;
+  }
+  [data-reveal] {
+    opacity: 1 !important;
+    transform: none !important;
+  }
+}
+
 /* src/Modal.css */
 .rx-scrim {
   position: fixed;

package/react/dist/index.d.ts

@@ -12,9 +12,11 @@ type ButtonProps = {
     iconRight?: string;
     iconOnly?: boolean;
     block?: boolean;
+    /** In flight: aria-busy, disabled, and the kit's indeterminate bars. */
+    busy?: boolean;
     children?: ReactNode;
 } & ButtonHTMLAttributes<HTMLButtonElement>;
-declare function Button({ variant, size, icon, iconRight, iconOnly, block, children, type, ...rest }: ButtonProps): react.JSX.Element;
+declare function Button({ variant, size, icon, iconRight, iconOnly, block, busy, children, type, disabled, ...rest }: ButtonProps): react.JSX.Element;
 
 declare function Badge({ variant, children }: {
     variant?: string;
@@ -55,4 +57,43 @@ declare function DataTable<T extends {
     name: string;
 }>({ columns, rows, pageSize, selected, onToggle, onTogglePage, }: DataTableProps<T>): react.JSX.Element;
 
-export { Badge, Button, type ButtonProps, Card, type Column, DataTable, type DataTableProps, Icon, Modal, type ModalProps };
+type SkeletonProps = {
+    /** A count of bars, or explicit widths when a ragged prose edge matters. */
+    lines?: number | string[];
+    width?: string;
+    height?: string;
+    radius?: string;
+    className?: string;
+};
+declare function Skeleton({ lines, width, height, radius, className }: SkeletonProps): react.JSX.Element;
+type SkeletonTableProps = {
+    rows?: number;
+    cols?: number;
+    head?: boolean;
+};
+declare function SkeletonTable({ rows, cols, head }: SkeletonTableProps): react.JSX.Element;
+type BusyRegionProps = {
+    busy: boolean;
+    /** Spoken while it works. */
+    label?: string;
+    /** Spoken when it finishes — the specific line ("14 invoices") beats "Loaded". */
+    message?: string;
+    /** Placeholder while busy. Defaults to a three-bar skeleton. */
+    placeholder?: ReactNode;
+    className?: string;
+    children?: ReactNode;
+};
+declare function BusyRegion({ busy, label, message, placeholder, className, children, }: BusyRegionProps): react.JSX.Element;
+type DeniedProps = {
+    title?: string;
+    sub?: string;
+    /** The scope or role the reader is missing, verbatim. */
+    need?: string;
+    icon?: string;
+    className?: string;
+    /** Buttons. Nothing is assumed about what a reader can do next. */
+    children?: ReactNode;
+};
+declare function Denied({ title, sub, need, icon, className, children, }: DeniedProps): react.JSX.Element;
+
+export { Badge, BusyRegion, type BusyRegionProps, Button, type ButtonProps, Card, type Column, DataTable, type DataTableProps, Denied, type DeniedProps, Icon, Modal, type ModalProps, Skeleton, type SkeletonProps, SkeletonTable, type SkeletonTableProps };

package/react/dist/index.js

@@ -24,8 +24,10 @@ function Button({
   iconRight,
   iconOnly,
   block,
+  busy,
   children,
   type = "button",
+  disabled,
   ...rest
 }) {
   const cls = cx(
@@ -38,11 +40,27 @@ function Button({
   const labelled = rest["aria-label"] != null || rest["aria-labelledby"] != null;
   const fallback = typeof children === "string" && children.trim() ? children.trim() : icon2;
   const named = iconOnly && !labelled && fallback ? { "aria-label": fallback, title: rest.title ?? fallback } : {};
-  return /* @__PURE__ */ jsxs("button", { type, className: cls, ...rest, ...named, children: [
-    icon2 && /* @__PURE__ */ jsx2(Icon, { name: icon2 }),
-    !iconOnly && children != null && /* @__PURE__ */ jsx2("span", { children }),
-    iconRight && /* @__PURE__ */ jsx2(Icon, { name: iconRight })
-  ] });
+  return /* @__PURE__ */ jsxs(
+    "button",
+    {
+      type,
+      className: cls,
+      disabled: disabled || busy,
+      "aria-disabled": disabled || busy ? true : void 0,
+      "aria-busy": busy ? true : void 0,
+      ...rest,
+      ...named,
+      children: [
+        icon2 && /* @__PURE__ */ jsx2(Icon, { name: icon2 }),
+        !iconOnly && children != null && /* @__PURE__ */ jsx2("span", { children }),
+        iconRight && /* @__PURE__ */ jsx2(Icon, { name: iconRight }),
+        busy && /* @__PURE__ */ jsxs("span", { className: "ui-btn__bars", children: [
+          /* @__PURE__ */ jsx2("i", {}),
+          /* @__PURE__ */ jsx2("i", {})
+        ] })
+      ]
+    }
+  );
 }
 
 // src/primitives/Badge.tsx
@@ -244,11 +262,85 @@ function DataTable({
     ] })
   ] });
 }
+
+// src/Loading.tsx
+import { jsx as jsx7, jsxs as jsxs5 } from "react/jsx-runtime";
+var cx2 = (...a) => a.filter(Boolean).join(" ");
+function Skeleton({ lines = 3, width, height, radius, className }) {
+  const widths = Array.isArray(lines) ? lines : null;
+  const n = widths ? widths.length : Math.max(1, lines);
+  const styleFor = (i) => {
+    const w = widths ? widths[i] : width;
+    if (!w && !height && !radius) return void 0;
+    return { ...w && { width: w }, ...height && { height }, ...radius && { borderRadius: radius } };
+  };
+  return /* @__PURE__ */ jsx7("div", { className: cx2("ui-skel", className), "aria-hidden": "true", children: Array.from({ length: n }, (_, i) => /* @__PURE__ */ jsx7("span", { className: "ui-skel__bar m-skeleton", style: styleFor(i) }, i)) });
+}
+function SkeletonTable({ rows = 5, cols = 4, head = true }) {
+  const cells = Array.from({ length: Math.max(1, cols) }, (_, i) => /* @__PURE__ */ jsx7("span", { className: "ui-skel__bar m-skeleton" }, i));
+  return /* @__PURE__ */ jsxs5(
+    "div",
+    {
+      className: "ui-skel ui-skel--table",
+      style: { "--skel-cols": Math.max(1, cols) },
+      "aria-hidden": "true",
+      children: [
+        head && /* @__PURE__ */ jsx7("div", { className: "ui-skel__row ui-skel__row--head", children: cells }),
+        Array.from({ length: Math.max(1, rows) }, (_, i) => /* @__PURE__ */ jsx7("div", { className: "ui-skel__row", children: cells }, i))
+      ]
+    }
+  );
+}
+function BusyRegion({
+  busy,
+  label = "Loading\u2026",
+  message = "Loaded",
+  placeholder,
+  className,
+  children
+}) {
+  return /* @__PURE__ */ jsxs5(
+    "div",
+    {
+      className: cx2("ui-busy", className),
+      role: "status",
+      "aria-live": "polite",
+      "aria-busy": busy,
+      children: [
+        /* @__PURE__ */ jsx7("span", { className: "ui-sr", children: busy ? label : message }),
+        /* @__PURE__ */ jsx7("div", { className: "ui-busy__body", children: busy ? placeholder ?? /* @__PURE__ */ jsx7(Skeleton, { lines: 3 }) : children })
+      ]
+    }
+  );
+}
+function Denied({
+  title = "You don\u2019t have access",
+  sub,
+  need,
+  icon: icon2 = "lock",
+  className,
+  children
+}) {
+  return /* @__PURE__ */ jsxs5("div", { className: cx2("ui-denied", className), children: [
+    /* @__PURE__ */ jsx7("div", { className: "ui-denied__seal", children: /* @__PURE__ */ jsx7(Icon, { name: icon2 }) }),
+    /* @__PURE__ */ jsx7("div", { className: "ui-denied__title", children: title }),
+    sub && /* @__PURE__ */ jsx7("div", { className: "ui-denied__sub", children: sub }),
+    need && /* @__PURE__ */ jsxs5("div", { className: "ui-denied__need", children: [
+      "Needs ",
+      /* @__PURE__ */ jsx7("code", { className: "ui-code", children: need })
+    ] }),
+    children && /* @__PURE__ */ jsx7("div", { className: "ui-denied__actions", children })
+  ] });
+}
 export {
   Badge,
+  BusyRegion,
   Button,
   Card,
   DataTable,
+  Denied,
   Icon,
-  Modal
+  Modal,
+  Skeleton,
+  SkeletonTable
 };

package/src/assets/icons.js

@@ -1,12 +1,13 @@
-// Line-icon set — 24×24, stroke=currentColor, 1.7 weight, round caps/joins.
-// House style is Feather/Lucide (Lucide is the maintained Feather; our glyphs
-// match it 1:1). Delivery is inline SVG strings: no runtime dependency, works
-// in any framework, and every glyph inherits `currentColor` + a consistent
-// stroke so it sits right next to our type.
+// Line-icon set — 24×24, stroke=currentColor, 1.7 weight, round caps/joins,
+// Lucide house style. Delivery is inline SVG strings, so there is no runtime
+// dependency and every glyph inherits `currentColor`.
 //
 // Each value is the INNER markup; icon() wraps it in the shared <svg>. Glyphs
 // are grouped by domain — the flat ICONS map is what icon() looks up, and
-// iconCategories drives the Storybook grid. Add a glyph to the right group.
+// iconCategories drives the Storybook grid.
+//
+// Naming, grouping and provenance, and the gates that hold them:
+// why: CONTRIBUTING.md#add-a-glyph
 
 const NAV = {
   chevronDown: '<path d="M6 9l6 6 6-6" stroke-linecap="round" stroke-linejoin="round"/>',
@@ -101,9 +102,6 @@ const COMMS = {
   logout: '<path d="M9 21H5a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h4"/><polyline points="16 17 21 12 16 7"/><line x1="21" y1="12" x2="9" y2="12"/>',
   plug: '<path d="M12 22v-5"/><path d="M15 8V2"/><path d="M17 8a1 1 0 0 1 1 1v4a4 4 0 0 1-4 4h-4a4 4 0 0 1-4-4V9a1 1 0 0 1 1-1z"/><path d="M9 8V2"/>',
   sparkle: '<path d="M11.017 2.814a1 1 0 0 1 1.966 0l1.051 5.558a2 2 0 0 0 1.594 1.594l5.558 1.051a1 1 0 0 1 0 1.966l-5.558 1.051a2 2 0 0 0-1.594 1.594l-1.051 5.558a1 1 0 0 1-1.966 0l-1.051-5.558a2 2 0 0 0-1.594-1.594l-5.558-1.051a1 1 0 0 1 0-1.966l5.558-1.051a2 2 0 0 0 1.594-1.594z"/><path d="M20 2v4"/><path d="M22 4h-4"/><circle cx="4" cy="20" r="2"/>',
-  card: '<rect x="1" y="4" width="22" height="16" rx="2" ry="2"/><line x1="1" y1="10" x2="23" y2="10"/>',
-  doc: '<path d="M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8z"/><polyline points="14 2 14 8 20 8"/><line x1="16" y1="13" x2="8" y2="13"/><line x1="16" y1="17" x2="8" y2="17"/><polyline points="10 9 9 9 8 9"/>',
-  chart: '<line x1="18" y1="20" x2="18" y2="10"/><line x1="12" y1="20" x2="12" y2="4"/><line x1="6" y1="20" x2="6" y2="14"/>',
 };
 
 const BRAND = {
@@ -140,5 +138,49 @@ export const icon = (name, cls = '') =>
 
 export const iconNames = Object.keys(ICONS);
 
+// Which controls may be an icon and nothing else — a closed list, not a
+// judgement call in review.
+//
+// The accessibility half was already held: every glyph is aria-hidden, so
+// button({ iconOnly }) names itself from `label`. That says a nameless icon
+// button cannot ship; it never said when a wordless one SHOULD. This does.
+//
+// A control whose action is on this list may drop its visible text. Everything
+// else carries a label — including glyphs that feel obvious in isolation, like
+// `gear` or `externalLink`, because a reader meets them one at a time and a
+// toolbar is not a legend. Adding an entry is a decision recorded here, which
+// is the point: the alternative rules read well and could not be gated.
+export const iconOnlyAllowed = {
+  x: 'close or dismiss',
+  copy: 'copy to clipboard',
+  moreHorizontal: 'overflow menu',
+  moreVertical: 'overflow menu',
+  chevronDown: 'expand or collapse',
+  chevronUp: 'expand or collapse',
+};
+
+// What a glyph means when a component picks it for the reader rather than a
+// caller naming it. Two rules hold the map together:
+//
+//   a CIRCLED glyph is a state the system is in — circleCheck, circleX,
+//   circleAlert. It is reported to you and you cannot click it.
+//   a BARE glyph is an action you can take — x dismisses, check confirms,
+//   trash deletes.
+//
+// That split is what a danger toast needed: it used to render the same bare `x`
+// twice, once meaning "this failed" and once meaning "make this go away". The
+// bare x is now reserved for the close button, and status took the circle
+// family the kit was already shipping and never using.
+export const iconMeanings = {
+  circleCheck: 'a state: it succeeded',
+  circleX: 'a state: it failed',
+  circleAlert: 'a state: it needs attention',
+  info: 'a state: something worth knowing, no action required',
+  bolt: 'a state: it happened, with no verdict attached',
+  x: 'an action: close or dismiss this',
+  check: 'an action: confirm this',
+  trash: 'an action: delete this',
+};
+
 export const sun = '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" aria-hidden="true" focusable="false"><circle cx="12" cy="12" r="4"/><path d="M12 2v2M12 20v2M4.9 4.9l1.4 1.4M17.7 17.7l1.4 1.4M2 12h2M20 12h2M4.9 19.1l1.4-1.4M17.7 6.3l1.4-1.4"/></svg>';
 export const moon = '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="M21 12.8A9 9 0 1 1 11.2 3a7 7 0 0 0 9.8 9.8z"/></svg>';

package/src/components/account-nav.js

@@ -3,7 +3,7 @@
 // shell.js and topbar.js need it and shell.js already imports topbar.js — the
 // other direction would be a cycle. shell.js re-exports ACCOUNT_NAV, which is
 // the published name docs/library.md documents.
-// why: docs/adr/0007-one-page-shell-built-from-the-kits-own-nav.md
+// why: docs/specification.md#the-page-shell
 import { esc } from './index.js';
 
 // nav.js item objects. Labels are raw text — every nav primitive escapes, so a

package/src/components/index.js

@@ -16,6 +16,10 @@ export const esc = (s) => String(s == null ? '' : s).replace(/[&<>"]/g, (c) => (
 // stops being decoration and becomes the control's ONLY accessible name. It is
 // mirrored into aria-label + title, and an empty label falls back to the icon
 // name rather than shipping a nameless button.
+//
+// That is the accessibility half, and it is not permission. WHEN a control may
+// go wordless is a closed list — `iconOnlyAllowed` in src/assets/icons.js — and
+// stories/guidelines/iconography.test.js reviews call sites against it.
 export function button({
   label = 'Button', variant = 'secondary', size = 'md', icon: ic, iconSvg, iconRight,
   block = false, disabled = false, busy = false, type = 'button', href, iconOnly = false,
@@ -217,8 +221,18 @@ export function switchToggle({ checked = false, disabled = false, name, label =
 export function callout({ variant, icon: ic = 'info', body } = {}) {
   return `<div class="${cx('ui-callout', variant && `ui-callout--${variant}`)}"><span class="ui-callout__icon">${icon(ic)}</span><div>${body}</div></div>`;
 }
-// Default icon per status — overridable with `icon`.
-const TOAST_ICON = { success: 'check', danger: 'x', warn: 'alert', info: 'info', neutral: 'bolt' };
+// Default icon per status — overridable with `icon`. The circle family is not
+// decoration: a circled glyph is a STATE the system reports, a bare one is an
+// ACTION you can take (iconMeanings in src/assets/icons.js).
+//
+// This used to read `success: 'check', danger: 'x', warn: 'alert'`, which made
+// a danger toast render the same bare `x` twice — once as the status, meaning
+// "this failed", once as the close button, meaning "make this go away". Status
+// took the circle glyphs the kit already shipped and never used, and the bare
+// `x` now belongs to the close button alone.
+const TOAST_ICON = {
+  success: 'circleCheck', danger: 'circleX', warn: 'circleAlert', info: 'info', neutral: 'bolt',
+};
 // A toast carries a status (colour) and a style (surface). Everything visual is
 // token-driven: the status modifier sets --toast-accent/-glow/-on, the style
 // modifier consumes them. `action` adds a trailing button ("Undo"/"Retry"),

package/src/components/loading.js

@@ -0,0 +1,126 @@
+// The pending and denied states of a SCREEN, not of one control.
+//
+// busyRegion() is one live region that outlives what it reports on; setBusy()
+// swaps its body and writes a line into the sr-only node already inside it.
+// Three things land in that body: skeleton() while it fetches, your markup once
+// the rows arrive, deniedState() when the answer came back 403.
+//
+// why: docs/specification.md#pending-and-denied-states
+import { icon } from '../assets/icons.js';
+import { button, esc } from './index.js';
+
+const cx = (...a) => a.filter(Boolean).join(' ');
+
+// ---- Skeleton ------------------------------------------------------------
+// The placeholder shape. `lines` is a count, or an array of widths when the
+// varied ragged edge of real prose matters (['100%','92%','60%']). `height`
+// makes it one solid block instead — a chart, a map, an avatar. The shimmer is
+// .m-skeleton from the motion library, so there is one animation to own and it
+// is already inside that library's reduced-motion net.
+export function skeleton({ lines = 3, width, height, radius, className = '' } = {}) {
+  const widths = Array.isArray(lines) ? lines : Array.isArray(width) ? width : null;
+  const n = widths ? widths.length : Math.max(1, lines | 0);
+  const styleFor = (i) => {
+    const w = widths ? widths[i] : (typeof width === 'string' ? width : null);
+    const bits = [w && `width:${w}`, height && `height:${height}`, radius && `border-radius:${radius}`];
+    const s = bits.filter(Boolean).join(';');
+    return s ? ` style="${esc(s)}"` : '';
+  };
+  const bars = Array.from({ length: n }, (_, i) =>
+    `<span class="ui-skel__bar m-skeleton"${styleFor(i)}></span>`).join('');
+  return `<div class="${cx('ui-skel', className)}" aria-hidden="true">${bars}</div>`;
+}
+
+// A table's worth of skeleton — `rows` × `cols` of bar, laid out on a grid so
+// the placeholder has the column rhythm the real table will have. Screens that
+// load a table are the common case, and hand-rolling this per screen is how
+// four slightly different loading tables get shipped.
+export function skeletonTable({ rows = 5, cols = 4, head = true } = {}) {
+  const row = (cls) => `<div class="${cls}">`
+    + Array.from({ length: Math.max(1, cols | 0) }, () => '<span class="ui-skel__bar m-skeleton"></span>').join('')
+    + '</div>';
+  const body = Array.from({ length: Math.max(1, rows | 0) }, () => row('ui-skel__row')).join('');
+  return `<div class="ui-skel ui-skel--table" style="--skel-cols:${Math.max(1, cols | 0)}" aria-hidden="true">`
+    + `${head ? row('ui-skel__row ui-skel__row--head') : ''}${body}</div>`;
+}
+
+// ---- The region ----------------------------------------------------------
+// `label` is what is spoken while it works, `readyLabel` the fallback for when
+// it finishes without the caller supplying a line. Both are parked on the
+// element so setBusy() can find them and the caller never repeats itself.
+//
+// `body` overrides the default skeleton (pass your own placeholder, or the
+// already-loaded content when the region starts ready).
+export function busyRegion({
+  label = 'Loading…', readyLabel = 'Loaded', busy = true,
+  body, lines = 3, className = '',
+} = {}) {
+  const inner = body != null ? body : skeleton({ lines });
+  return `<div class="${cx('ui-busy', className)}" data-busy`
+    + ` data-busy-label="${esc(label)}" data-busy-ready="${esc(readyLabel)}"`
+    + ` role="status" aria-live="polite" aria-busy="${busy ? 'true' : 'false'}">`
+    + `<span class="ui-sr" data-busy-msg>${esc(busy ? label : readyLabel)}</span>`
+    + `<div class="ui-busy__body" data-busy-body>${inner}</div>`
+    + '</div>';
+}
+
+// Flip a region between busy and ready, and say so. Writing into
+// [data-busy-msg] IS the announcement. Callers pass `message` for the specific
+// line ("14 invoices", "You don't have access to this report"); the region's
+// own labels are the fallback.
+//
+// Accepts the region, a selector, or any ancestor of it. Returns the region, or
+// null when there is nothing to update — safe to call against a torn-down view.
+export function setBusy(root, { busy = false, message, body } = {}) {
+  const el = typeof root === 'string' ? document.querySelector(root) : root;
+  if (!el || typeof el.querySelector !== 'function') return null;
+  const region = el.matches && el.matches('[data-busy]') ? el : el.querySelector('[data-busy]');
+  if (!region) return null;
+
+  region.setAttribute('aria-busy', busy ? 'true' : 'false');
+  if (body != null) {
+    const slot = region.querySelector('[data-busy-body]');
+    if (slot) slot.innerHTML = body;
+  }
+  const msg = region.querySelector('[data-busy-msg]');
+  if (msg) {
+    const fallback = busy
+      ? (region.dataset.busyLabel || 'Loading…')
+      : (region.dataset.busyReady || 'Loaded');
+    msg.textContent = message == null ? fallback : String(message);
+  }
+  return region;
+}
+
+// ---- Permission denied ---------------------------------------------------
+// The 403 screen. Same shape as emptyState() — a mark, a title, a line, some
+// actions — because to a reader they are the same event: the thing you came for
+// is not here. What separates them is that this one owes an explanation, so
+// `need` is a first-class slot rather than something to bury in `sub`.
+//
+// `need` names the scope or role the reader is missing, verbatim, as code. A
+// reader who can act on "you need reports.read" acts on it; "insufficient
+// permissions" sends them to open a ticket to find out what to ask for.
+//
+// No role and no live region here — see the file header. When this lands as the
+// answer to a fetch, put it inside a busyRegion() and the region announces it.
+export function deniedState({
+  title = 'You don’t have access',
+  sub = '',
+  need = '',
+  actions = [],
+  icon: ic = 'lock',
+  className = '',
+} = {}) {
+  const needEl = need
+    ? `<div class="ui-denied__need">Needs <code class="ui-code">${esc(need)}</code></div>`
+    : '';
+  const actionsEl = actions.length
+    ? `<div class="ui-denied__actions">${actions.map((a) => button({ size: 'md', ...a })).join('')}</div>`
+    : '';
+  return `<div class="${cx('ui-denied', className)}">`
+    + `<div class="ui-denied__seal" aria-hidden="true">${icon(ic)}</div>`
+    + `<div class="ui-denied__title">${esc(title)}</div>`
+    + `${sub ? `<div class="ui-denied__sub">${esc(sub)}</div>` : ''}`
+    + `${needEl}${actionsEl}</div>`;
+}

package/src/components/shell.js

@@ -3,7 +3,7 @@
 // with a breadcrumb trail the caller owns. `accountShell()` is a thin preset
 // over it that keeps the topbar, so the published /account API still works.
 // Call wireTopbar() once after mounting to wire the account menu + theme toggle.
-// why: docs/adr/0007-one-page-shell-built-from-the-kits-own-nav.md
+// why: docs/specification.md#the-page-shell
 import { topbar as productTopbar } from './topbar.js';
 import { esc, icon } from './index.js';
 import { sidebarNav, breadcrumbs } from './nav.js';
@@ -89,16 +89,17 @@ const toTopbar = (t) => {
   return out;
 };
 
-// `maxWidth` lands inside a style attribute, which is a declaration list: esc()
-// stops a quote closing the attribute, and `;` is the character that matters
-// there. So a length is all this accepts — a number and a unit the reading
-// column can use, or `none`. Anything else falls back to the default rather
-// than throwing, because a shell that throws mid-render takes the page with it.
-const MAIN_MAX = '860px';
+// `maxWidth` lands inside a style attribute, so a length is all this accepts —
+// a number and a unit, or `none`. Anything else yields '' and the caller writes
+// no style attribute, letting layout.css fall through to --measure. It must
+// REMOVE the property rather than pass a default or a bad value on: a custom
+// property accepts any token stream, so garbage is a valid declaration that
+// drops the column to `none`, the full track.
+// why: docs/specification.md#widths
 const LENGTH = /^(?:\d+|\d*\.\d+)(?:px|rem|em|ch|%|vw)$/;
 const mainMax = (v) => {
   const s = str(v).trim();
-  return s === 'none' || LENGTH.test(s) ? s : MAIN_MAX;
+  return s === 'none' || LENGTH.test(s) ? s : '';
 };
 
 // The one pass. Each key names the function that settles it; nothing else in
@@ -194,7 +195,7 @@ export function appShell(options = {}) {
       ${rail}
       ${railUser(account)}
     </div>
-    <main class="ui-app__main" style="--ui-app-main: ${maxWidth}">
+    <main class="ui-app__main"${maxWidth ? ` style="--ui-app-main: ${maxWidth}"` : ''}>
       ${crumbs.length ? breadcrumbs({ items: crumbs }) : ''}
       ${title ? `<h1>${title}</h1>` : ''}
       ${sub ? `<p class="ui-app__sub">${sub}</p>` : ''}

package/src/index.css

@@ -1,12 +1,16 @@
 /* ============================================================================
  * apliteni-ui — full stylesheet.
- * Import once (`import 'apliteni-ui/css'`) or cherry-pick from src/styles/*.
+ * Import once: `import 'apliteni-ui/css'`. A single component sheet is NOT
+ * addressable — package.json `exports` has no wildcard for ./styles/*, so a deep
+ * path into src/styles/ does not resolve. To take one component, read it by name
+ * through `apliteni-ui/inline` (`import { topbarCss } from …`).
  * Requires the Poppins font (loaded by the host page or Storybook preview).
  * ========================================================================== */
 @import "./tokens/brand.generated.css";
 @import "./tokens/tokens.css";
 @import "./tokens/accents.css";
 @import "./styles/base.css";
+@import "./styles/reduced-motion.css";
 @import "./styles/motion.css";
 @import "./styles/button.css";
 @import "./styles/card.css";
@@ -27,3 +31,4 @@
 @import "./styles/layout.css";
 @import "./styles/feedback.css";
 @import "./styles/success.css";
+@import "./styles/loading.css";

package/src/index.js

@@ -12,6 +12,7 @@ export * from './components/footer.js';
 export * from './components/feedback.js';
 export * from './components/toasts.js';
 export * from './components/success.js';
+export * from './components/loading.js';
 export * from './assets/icons.js';
 export * from './assets/brand.js';
 export * from './motion.js';

package/src/inline.js

@@ -28,6 +28,7 @@ export const topbarCss = read('styles/topbar.css');
 // Individual component stylesheets, addressable by name.
 export const styles = {
   base: baseCss,
+  reducedMotion: read('styles/reduced-motion.css'),
   motion: read('styles/motion.css'),
   button: read('styles/button.css'),
   card: read('styles/card.css'),
@@ -48,12 +49,14 @@ export const styles = {
   layout: read('styles/layout.css'),
   feedback: read('styles/feedback.css'),
   success: read('styles/success.css'),
+  loading: read('styles/loading.css'),
 };
 
 // Everything, in the same order as index.css. `tokensCss` first so cascade is right.
 export const cssText = [
   tokensCss,
   styles.base,
+  styles.reducedMotion,
   styles.motion,
   styles.button,
   styles.card,
@@ -74,4 +77,5 @@ export const cssText = [
   styles.layout,
   styles.feedback,
   styles.success,
+  styles.loading,
 ].join('\n');

package/src/styles/badge.css

@@ -72,7 +72,7 @@
 .ui-dot.is-live {
   background: var(--green);
   box-shadow: 0 0 0 0 var(--glow-green);
-  animation: ui-pulse 2s var(--ease) infinite;
+  animation: ui-pulse 2s var(--ease) infinite; /* motion: ambient — a liveness heartbeat, not a response to anything the reader did */
 }
 @keyframes ui-pulse {
   0% { box-shadow: 0 0 0 0 color-mix(in srgb, var(--green) 55%, transparent); }

package/src/styles/base.css

@@ -88,7 +88,7 @@ a {
 }
 
 /* Layout helpers used by the example apps */
-.ui-container { width: 100%; max-width: 1180px; margin: 0 auto; padding: 0 clamp(14px, 2.4vw, 26px); }
+.ui-container { width: 100%; max-width: var(--container); margin: 0 auto; padding: 0 clamp(14px, 2.4vw, 26px); }
 .ui-stack > * + * { margin-top: var(--space-4); }
 
 /* Section eyebrow — uppercase caption used across cards and headers */