@apliteni/apliteni-ui 0.31.0 → 0.33.0

package/README.md

@@ -4,38 +4,37 @@
 [![license: MIT](https://img.shields.io/npm/l/@apliteni/apliteni-ui?color=3b9dff)](./LICENSE)
 [![live: ui.apli.tech](https://img.shields.io/badge/live-ui.apli.tech-9b5dff)](https://ui.apli.tech)
 
-The Apliteni design system & UI kit — one source of UI for every product surface
-(the strategy deck, the text portal, `/account`, the operating model, and whatever
-ships next).
+The Apliteni design system and UI kit supplies shared UI for the strategy deck,
+the text portal, `/account`, the operating model, and future product surfaces.
 
-Two layers over one set of design tokens: framework-agnostic **HTML + CSS**, and
-**React components** for stateful surfaces. Themeable dark and light with **accent
-sub-themes**. Showcased and reviewed in **Storybook**, and published on **ui.apli.tech**.
+It provides framework-agnostic **HTML + CSS** and **React components** for stateful
+surfaces, with shared tokens, dark and light themes, and **accent sub-themes**.
+Review components in **Storybook** at **ui.apli.tech**.
 
-- 🎨 **Live site + Storybook** → [ui.apli.tech](https://ui.apli.tech)
-- 📦 **Package** → [`@apliteni/apliteni-ui`](https://www.npmjs.com/package/@apliteni/apliteni-ui) (public npm)
-- ⚛️ **React components** → `@apliteni/apliteni-ui/react` — a subpath of the same package, source in [`react/`](./react)
+- **Live site + Storybook** → [ui.apli.tech](https://ui.apli.tech)
+- **Package** → [`@apliteni/apliteni-ui`](https://www.npmjs.com/package/@apliteni/apliteni-ui) (public npm)
+- **React components** → `@apliteni/apliteni-ui/react` — a subpath of the same package, source in [`react/`](./react)
 
 ## HTML + CSS *and* React
 
-The core is HTML + CSS because the strategy portal (`apliteni/strategy`, `viz/`)
-server-renders HTML strings (`.mjs` modules), not a component framework. So the kit
-ships the same shape: token CSS + component CSS + tiny HTML-string factories. That
-makes it a *true* single source of truth — the portal imports it with no rewrite and
-no framework drift. Storybook (`@storybook/html-vite`) renders exactly what ships.
+The strategy portal (`apliteni/strategy`, `viz/`) server-renders HTML strings from
+`.mjs` modules without a component framework. The kit supplies token CSS, component
+CSS, and HTML-string factories that the portal can import without a rewrite.
+Storybook (`@storybook/html-vite`) renders those same strings.
 
-React sits on top for surfaces that hold real client state — dashboards, tables,
-filters, forms. Those components render the same `.ui-*` classes and the same tokens
-as the vanilla kit, so the two layers can't drift.
+React components handle client state in dashboards, tables, filters, and forms.
+They use the vanilla kit's `.ui-*` classes and tokens.
 
 **Which one:** does the surface hold meaningful client state? No → the HTML-string
 factories below. Yes → the [React components](#react-components-stateful-surfaces).
 
-Either layer follows the same UI rules — which component to reach for, the states it
-owes, how colour and wording work. They live in the **Guidelines** section of Storybook,
-which opens on
-[an overview of the five pages](https://ui.apli.tech/storybook/?path=/story/guidelines-overview--overview)
-and what the kit does and does not yet meet. Worth reading before you design a screen.
+Either layer follows the same UI rules — what one page may hold, which component to reach
+for, the states it owes, how colour and wording work. They live in the **Guidelines** section
+of Storybook, which opens on
+[an overview of every page](https://ui.apli.tech/storybook/?path=/story/guidelines-overview--overview)
+and what the kit does and does not yet meet.
+[The page](https://ui.apli.tech/storybook/?path=/story/guidelines-the-page--the-page) is the one
+to read before you design a screen: the limits one page keeps, whatever it is about.
 
 ## Install
 
@@ -67,10 +66,9 @@ tables, fields, paragraphs, chat, which is most of an application. Weights 300-7
 <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Poppins:wght@300;400;500;600;700&family=IBM+Plex+Sans:wght@300;400;500;600;700&display=swap">
 ```
 
-Load only one of them and the other falls through to the system stack behind it, without
-saying so. Want the old
-single-family look back? Set both roles to the same family in your own stylesheet, after the
-kit's:
+If either font is missing, that role falls back to its system stack, and nothing says so.
+For the old single-family appearance, set both roles to the same family in your stylesheet,
+after the kit's:
 
 ```css
 :root { --font-sans: var(--font-display); }
@@ -82,7 +80,7 @@ The whole `/account` layout (topbar + sticky sidebar + page body) ships as one
 factory, so every product renders the same account shell instead of re-building it:
 
 ```js
-import { accountShell, card, switchToggle, wireTopbar } from '@apliteni/apliteni-ui';
+import { accountShell, card, switchToggle, wireTopbar, wireShell } from '@apliteni/apliteni-ui';
 
 el.innerHTML = accountShell({
   word: 'Strategy',                              // the product word in the topbar
@@ -93,8 +91,10 @@ el.innerHTML = accountShell({
   body: card({ title: 'Appearance', body: switchToggle({ label: 'Reduce motion' }) }),
 });
 wireTopbar(el);                                  // menus, theme toggle, segmented controls
+wireShell(el);                                   // the toggle that folds the rail, the reader's menu, the nav's groups
 
 // Custom sidebar nav? pass `nav: [['prefs','gear','Preferences'], ['billing','wallet','Billing']]`
+// A page that will never call wireShell()? pass `collapsible: false` and no toggle is drawn
 ```
 
 Server-rendered apps that inline CSS (like the strategy portal) import the stylesheet
@@ -111,18 +111,17 @@ import { tokensCss, topbarCss, cssText } from '@apliteni/apliteni-ui/inline';
 same tokens, TypeScript types included. They ship as a **subpath of this package**,
 not as a package of their own: one install, one version, one pin.
 
-**You install React yourself.** The kit declares no dependency on it — not a
-dependency, not a peer — so npm will not warn you and will not pull it in. Bring your
-own `react` and `react-dom`, version 18 or newer:
+Install `react` and `react-dom`, version 18 or newer, yourself. The kit declares
+neither a regular nor a peer dependency on React, so npm neither installs it nor
+warns when it is missing:
 
 ```bash
 npm install @apliteni/apliteni-ui react react-dom
 ```
 
-Miss them and the import of `@apliteni/apliteni-ui/react` fails at build or at
-runtime with a module-not-found error for `react`. Everything else in the kit is
-unaffected, so a plain HTML consumer installs the kit alone and never gets React in
-its tree.
+Without them, importing `@apliteni/apliteni-ui/react` fails at build or runtime with
+a module-not-found error for `react`. Plain HTML consumers can install the kit alone;
+the other entry points are unaffected and do not bring React into the dependency tree.
 
 ```tsx
 import '@apliteni/apliteni-ui/css';        // kit tokens + .ui-* classes

package/package.json

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

package/react/README.md

@@ -1,8 +1,7 @@
 # React components
 
-Source for the kit's React layer — for surfaces that hold real client state
-(dashboards, tables, filters, forms). They render the same `.ui-*` classes and
-tokens as the vanilla kit, so the two layers can't drift.
+The kit's React layer supplies components for stateful surfaces: dashboards, tables,
+filters, and forms. They use the vanilla kit's `.ui-*` classes and tokens.
 
 This directory is a **private workspace**, not a package. It builds to `react/dist/`
 and ships as the `@apliteni/apliteni-ui/react` subpath of the kit — one package, one
@@ -29,7 +28,7 @@ import '@apliteni/apliteni-ui/react/css';  // React components' shell styles (mo
 import { DataTable, Modal, Button } from '@apliteni/apliteni-ui/react';
 ```
 
-Components: `DataTable`, `Pagination`, `Modal`, `Drawer`, `CommandPalette`, `Button`, `Badge`, `Card`, `Icon`.
+Components: `DataTable`, `Pagination`, `StatBand`, `Modal`, `Drawer`, `CommandPalette`, `Button`, `Badge`, `Card`, `Icon`.
 
 `CommandPalette` renders the kit's `commandPalette()` markup, class for class, and imports the
 kit's ranking rather than repeating it — so a palette a server rendered and the same palette
@@ -105,16 +104,15 @@ npm run storybook -w react   # http://localhost:6007
 npm run build                # tsup -> react/dist/
 ```
 
-6007 is a request, not a promise: if something else already holds it, Storybook
-walks upward to the next free port. The root Storybook composes these components
-by following that drift — it probes 6007 through 6016 (the window Storybook's own
+If port 6007 is occupied, Storybook tries higher ports until one is free. The root
+Storybook composes these components by following that drift — it probes 6007 through 6016 (the window Storybook's own
 port-finder searches) and takes the first one whose `index.json` lists every story
 file this workspace has on disk. A stranger on the port fails that check and is
 never shown under "React components"; the section is simply absent, and the root
 Storybook's terminal says which ports it tried and what it found.
 
-The probe runs once, while the root Storybook boots. Start this one afterwards and
-you have to restart the root Storybook before it appears.
+The probe runs once when the root Storybook starts. If you start the React Storybook
+later, restart the root Storybook to include it.
 
 The bare `@apliteni/apliteni-ui` specifier in this source resolves to the kit itself
 once installed. In the repo there is no copy to resolve to, so `kit-alias.ts` points

package/react/dist/index.css

@@ -17,6 +17,15 @@
   }
 }
 
+/* ../src/styles/field-zoom.css */
+@media (pointer: coarse) {
+  input:not(:where([type=button], [type=checkbox], [type=color], [type=file], [type=hidden], [type=image], [type=radio], [type=range], [type=reset], [type=submit])),
+  select,
+  textarea {
+    font-size: 16px !important;
+  }
+}
+
 /* src/Modal.css */
 .rx-scrim {
   position: fixed;
@@ -34,10 +43,9 @@
 }
 .rx-modal {
   width: min(480px, 92vw);
-  background: var(--surface);
+  background: var(--bg-elevated);
   border: 1px solid var(--border);
   border-radius: var(--radius-xl);
-  box-shadow: var(--shadow-lg);
   overflow: hidden;
   transform: translateY(8px);
   transition: transform var(--dur-med) var(--ease);

package/react/dist/index.d.ts

@@ -31,6 +31,30 @@ declare function Card({ title, sub, level, children }: {
     children?: ReactNode;
 }): react.JSX.Element;
 
+type StatTone = 'good' | 'bad' | 'neutral';
+type StatVariant = 'band' | 'tiles' | 'open';
+interface StatDelta {
+    value: string | null;
+    tone?: StatTone;
+    basis?: string;
+    direction?: 'up' | 'down' | 'flat';
+    none?: string;
+}
+interface StatFigure {
+    label: string;
+    value: ReactNode;
+    delta?: StatDelta;
+    trend?: ReactNode;
+}
+interface StatBandProps {
+    stats: StatFigure[];
+    variant?: StatVariant;
+    basis?: string;
+    label?: string;
+    id?: string;
+}
+declare function StatBand({ stats, variant, basis, label, id }: StatBandProps): react.JSX.Element;
+
 type ModalProps = {
     open: boolean;
     title: string;
@@ -222,4 +246,4 @@ declare function Denied({ title, sub, need, icon, className, children, }: Denied
 declare const PAGE_SIZES: readonly number[];
 declare const DEFAULT_PAGE_SIZE: number;
 
-export { Badge, BusyRegion, type BusyRegionProps, Button, type ButtonProps, Card, type Column, type CommandGroup, type CommandItem, CommandPalette, type CommandPaletteProps, DEFAULT_PAGE_SIZE, DataTable, type DataTableProps, Denied, type DeniedProps, Drawer, type DrawerProps, Icon, Modal, type ModalProps, PAGE_SIZES, Pagination, type PaginationProps, Skeleton, type SkeletonProps, SkeletonTable, type SkeletonTableProps, type TableSort, sortTableRows };
+export { Badge, BusyRegion, type BusyRegionProps, Button, type ButtonProps, Card, type Column, type CommandGroup, type CommandItem, CommandPalette, type CommandPaletteProps, DEFAULT_PAGE_SIZE, DataTable, type DataTableProps, Denied, type DeniedProps, Drawer, type DrawerProps, Icon, Modal, type ModalProps, PAGE_SIZES, Pagination, type PaginationProps, Skeleton, type SkeletonProps, SkeletonTable, type SkeletonTableProps, StatBand, type StatBandProps, type StatDelta, type StatFigure, type StatTone, type StatVariant, type TableSort, sortTableRows };