@ponchia/ui 0.3.1 → 0.3.3

package/README.md

@@ -25,6 +25,12 @@ flat hairline borders, restrained motion. CSS-first and framework-agnostic.
 > }
 > ```
 
+> **For AI agents / LLMs.** The package ships `llms.txt` at its root —
+> point a coding agent at `node_modules/@ponchia/ui/llms.txt` for a
+> self-contained orientation. The full class catalog
+> (`docs/reference.md`) and the token contract (`docs/theming.md`) also
+> ship in the tarball, so an offline agent never has to guess at the API.
+
 **[Live demo →](https://ponchia.github.io/bronto-ui/)** — the kitchen
 sink (every component, light/dark, RTL, theming) deployed from `demo/`.
 

package/classes/index.d.ts

@@ -1,7 +1,16 @@
 /** @ponchia/ui — GENERATED from classes/index.js by scripts/gen-dts.mjs.
  *  Do not edit by hand; run `npm run dts:build`. Drift-checked in CI. */
 
-export type ClassValue = string | false | null | undefined | ClassValue[];
+// Mirrors clsx's permissive input: `number`/`boolean` accepted so the
+// idiomatic React `reactNode && 'cls'` guard (where the node may be 0 or
+// '') type-checks. The runtime `cx` skips every falsy value regardless.
+export type ClassValue =
+  | string
+  | number
+  | boolean
+  | null
+  | undefined
+  | ClassValue[];
 
 /** The flat registry of every class @ponchia/ui defines (literal). */
 export declare const cls: {
@@ -10,20 +19,35 @@ export declare const cls: {
   readonly buttonSubtle: 'ui-button--subtle';
   readonly buttonDanger: 'ui-button--danger';
   readonly buttonIcon: 'ui-button--icon';
+  readonly buttonSm: 'ui-button--sm';
+  readonly buttonLg: 'ui-button--lg';
   readonly card: 'ui-card';
   readonly cardHead: 'ui-card__head';
   readonly cardAccent: 'ui-card--accent';
   readonly cardInteractive: 'ui-card--interactive';
+  readonly stat: 'ui-stat';
+  readonly statgrid: 'ui-statgrid';
+  readonly statLabel: 'ui-stat__label';
+  readonly statValue: 'ui-stat__value';
+  readonly statDelta: 'ui-stat__delta';
+  readonly num: 'ui-num';
+  readonly numPos: 'ui-num--pos';
+  readonly numNeg: 'ui-num--neg';
+  readonly numMuted: 'ui-num--muted';
   readonly badge: 'ui-badge';
   readonly badgeAccent: 'ui-badge--accent';
   readonly badgeSuccess: 'ui-badge--success';
   readonly badgeWarning: 'ui-badge--warning';
   readonly badgeDanger: 'ui-badge--danger';
+  readonly badgeMuted: 'ui-badge--muted';
+  readonly badgeDot: 'ui-badge--dot';
   readonly chip: 'ui-chip';
   readonly chipAccent: 'ui-chip--accent';
   readonly link: 'ui-link';
   readonly linkArrow: 'ui-link--arrow';
+  readonly linkCta: 'ui-link--cta';
   readonly keyValue: 'ui-key-value';
+  readonly emptyState: 'ui-empty-state';
   readonly dot: 'ui-dot';
   readonly dotAccent: 'ui-dot--accent';
   readonly dotSuccess: 'ui-dot--success';
@@ -33,6 +57,10 @@ export declare const cls: {
   readonly dotgrid: 'ui-dotgrid';
   readonly dotgridAccent: 'ui-dotgrid--accent';
   readonly dotgridDense: 'ui-dotgrid--dense';
+  readonly dotmatrix: 'ui-dotmatrix';
+  readonly dotmatrixCell: 'ui-dotmatrix__cell';
+  readonly dotmatrixCellHot: 'ui-dotmatrix__cell--hot';
+  readonly dotmatrixCellAccent: 'ui-dotmatrix__cell--accent';
   readonly dotfield: 'ui-dotfield';
   readonly dotrule: 'ui-dotrule';
   readonly dotbar: 'ui-dotbar';
@@ -145,14 +173,17 @@ export declare const cls: {
   readonly status: 'ui-status';
   readonly eyebrow: 'ui-eyebrow';
   readonly eyebrowMuted: 'ui-eyebrow--muted';
+  readonly eyebrowSm: 'ui-eyebrow--sm';
   readonly prose: 'ui-prose';
   readonly proseCompact: 'ui-prose--compact';
   readonly quote: 'ui-quote';
   readonly quoteCite: 'ui-quote__cite';
   readonly container: 'ui-container';
   readonly containerNarrow: 'ui-container--narrow';
+  readonly containerWide: 'ui-container--wide';
   readonly skiplink: 'ui-skiplink';
   readonly siteheader: 'ui-siteheader';
+  readonly siteheaderSticky: 'ui-siteheader--sticky';
   readonly siteheaderBrand: 'ui-siteheader__brand';
   readonly siteheaderActions: 'ui-siteheader__actions';
   readonly sitenav: 'ui-sitenav';
@@ -186,6 +217,7 @@ export declare const cls: {
   readonly appRailBrand: 'ui-app-rail__brand';
   readonly appRailToggle: 'ui-app-rail__toggle';
   readonly appRailFoot: 'ui-app-rail__foot';
+  readonly appRailAccount: 'ui-app-rail__account';
   readonly appTopbar: 'ui-app-topbar';
   readonly appTopbarTitle: 'ui-app-topbar__title';
   readonly appToolbar: 'ui-app-toolbar';
@@ -216,19 +248,25 @@ export declare function cx(...parts: ClassValue[]): string;
 export interface ButtonOpts {
   variant?: 'ghost' | 'subtle' | 'danger';
   icon?: boolean;
+  size?: 'sm' | 'lg';
 }
 export interface CardOpts {
   accent?: boolean;
   interactive?: boolean;
 }
 export interface BadgeOpts {
-  tone?: 'accent' | 'success' | 'warning' | 'danger';
+  tone?: 'accent' | 'success' | 'warning' | 'danger' | 'muted';
+  dot?: boolean;
+}
+export interface NumOpts {
+  tone?: 'pos' | 'neg' | 'muted';
 }
 export interface ChipOpts {
   accent?: boolean;
 }
 export interface LinkOpts {
   arrow?: boolean;
+  cta?: boolean;
 }
 export interface DotOpts {
   tone?: 'accent' | 'success' | 'warning' | 'danger';
@@ -244,6 +282,7 @@ export interface TableOpts {
 }
 export interface EyebrowOpts {
   muted?: boolean;
+  sm?: boolean;
 }
 export interface HintOpts {
   error?: boolean;
@@ -272,6 +311,8 @@ export interface DotbarOpts {
 }
 export interface ModalOpts {
   drawer?: boolean;
+  /** Controlled non-dialog usage — adds the is-open state (focus-trap is yours). */
+  open?: boolean;
 }
 export interface TabOpts {
   active?: boolean;
@@ -284,6 +325,7 @@ export interface ProseOpts {
 }
 export interface ContainerOpts {
   narrow?: boolean;
+  wide?: boolean;
 }
 export interface TagOpts {
   accent?: boolean;
@@ -293,6 +335,7 @@ export interface Ui {
   button(opts?: ButtonOpts): string;
   card(opts?: CardOpts): string;
   badge(opts?: BadgeOpts): string;
+  num(opts?: NumOpts): string;
   chip(opts?: ChipOpts): string;
   link(opts?: LinkOpts): string;
   dot(opts?: DotOpts): string;

package/classes/index.js

@@ -23,20 +23,35 @@ export const cls = Object.freeze({
   buttonSubtle: 'ui-button--subtle',
   buttonDanger: 'ui-button--danger',
   buttonIcon: 'ui-button--icon',
+  buttonSm: 'ui-button--sm',
+  buttonLg: 'ui-button--lg',
   card: 'ui-card',
   cardHead: 'ui-card__head',
   cardAccent: 'ui-card--accent',
   cardInteractive: 'ui-card--interactive',
+  stat: 'ui-stat',
+  statgrid: 'ui-statgrid',
+  statLabel: 'ui-stat__label',
+  statValue: 'ui-stat__value',
+  statDelta: 'ui-stat__delta',
+  num: 'ui-num',
+  numPos: 'ui-num--pos',
+  numNeg: 'ui-num--neg',
+  numMuted: 'ui-num--muted',
   badge: 'ui-badge',
   badgeAccent: 'ui-badge--accent',
   badgeSuccess: 'ui-badge--success',
   badgeWarning: 'ui-badge--warning',
   badgeDanger: 'ui-badge--danger',
+  badgeMuted: 'ui-badge--muted',
+  badgeDot: 'ui-badge--dot',
   chip: 'ui-chip',
   chipAccent: 'ui-chip--accent',
   link: 'ui-link',
   linkArrow: 'ui-link--arrow',
+  linkCta: 'ui-link--cta',
   keyValue: 'ui-key-value',
+  emptyState: 'ui-empty-state',
   // dots
   dot: 'ui-dot',
   dotAccent: 'ui-dot--accent',
@@ -47,6 +62,10 @@ export const cls = Object.freeze({
   dotgrid: 'ui-dotgrid',
   dotgridAccent: 'ui-dotgrid--accent',
   dotgridDense: 'ui-dotgrid--dense',
+  dotmatrix: 'ui-dotmatrix',
+  dotmatrixCell: 'ui-dotmatrix__cell',
+  dotmatrixCellHot: 'ui-dotmatrix__cell--hot',
+  dotmatrixCellAccent: 'ui-dotmatrix__cell--accent',
   dotfield: 'ui-dotfield',
   dotrule: 'ui-dotrule',
   dotbar: 'ui-dotbar',
@@ -166,6 +185,7 @@ export const cls = Object.freeze({
   // typography / utilities
   eyebrow: 'ui-eyebrow',
   eyebrowMuted: 'ui-eyebrow--muted',
+  eyebrowSm: 'ui-eyebrow--sm',
   prose: 'ui-prose',
   proseCompact: 'ui-prose--compact',
   quote: 'ui-quote',
@@ -173,8 +193,10 @@ export const cls = Object.freeze({
   // site shell
   container: 'ui-container',
   containerNarrow: 'ui-container--narrow',
+  containerWide: 'ui-container--wide',
   skiplink: 'ui-skiplink',
   siteheader: 'ui-siteheader',
+  siteheaderSticky: 'ui-siteheader--sticky',
   siteheaderBrand: 'ui-siteheader__brand',
   siteheaderActions: 'ui-siteheader__actions',
   sitenav: 'ui-sitenav',
@@ -210,6 +232,7 @@ export const cls = Object.freeze({
   appRailBrand: 'ui-app-rail__brand',
   appRailToggle: 'ui-app-rail__toggle',
   appRailFoot: 'ui-app-rail__foot',
+  appRailAccount: 'ui-app-rail__account',
   appTopbar: 'ui-app-topbar',
   appTopbarTitle: 'ui-app-topbar__title',
   appToolbar: 'ui-app-toolbar',
@@ -245,26 +268,37 @@ export function cx(...parts) {
 const j = (...p) => p.filter(Boolean).join(' ');
 
 export const ui = {
-  button: ({ variant, icon } = {}) =>
+  button: ({ variant, icon, size } = {}) =>
     j(
       cls.button,
       variant === 'ghost' && cls.buttonGhost,
       variant === 'subtle' && cls.buttonSubtle,
       variant === 'danger' && cls.buttonDanger,
       icon && cls.buttonIcon,
+      size === 'sm' && cls.buttonSm,
+      size === 'lg' && cls.buttonLg,
     ),
   card: ({ accent, interactive } = {}) =>
     j(cls.card, accent && cls.cardAccent, interactive && cls.cardInteractive),
-  badge: ({ tone } = {}) =>
+  badge: ({ tone, dot } = {}) =>
     j(
       cls.badge,
       tone === 'accent' && cls.badgeAccent,
       tone === 'success' && cls.badgeSuccess,
       tone === 'warning' && cls.badgeWarning,
       tone === 'danger' && cls.badgeDanger,
+      tone === 'muted' && cls.badgeMuted,
+      dot && cls.badgeDot,
+    ),
+  num: ({ tone } = {}) =>
+    j(
+      cls.num,
+      tone === 'pos' && cls.numPos,
+      tone === 'neg' && cls.numNeg,
+      tone === 'muted' && cls.numMuted,
     ),
   chip: ({ accent } = {}) => j(cls.chip, accent && cls.chipAccent),
-  link: ({ arrow } = {}) => j(cls.link, arrow && cls.linkArrow),
+  link: ({ arrow, cta } = {}) => j(cls.link, arrow && cls.linkArrow, cta && cls.linkCta),
   dot: ({ tone, live } = {}) =>
     j(
       cls.dot,
@@ -283,7 +317,7 @@ export const ui = {
       density === 'comfortable' && cls.tableComfortable,
       lined && cls.tableLined,
     ),
-  eyebrow: ({ muted } = {}) => j(cls.eyebrow, muted && cls.eyebrowMuted),
+  eyebrow: ({ muted, sm } = {}) => j(cls.eyebrow, muted && cls.eyebrowMuted, sm && cls.eyebrowSm),
   hint: ({ error } = {}) => j(cls.hint, error && cls.hintError),
   cluster: ({ between } = {}) => j(cls.cluster, between && cls.clusterBetween),
   stagger: ({ auto } = {}) => j(cls.stagger, auto && cls.staggerAuto),
@@ -307,12 +341,13 @@ export const ui = {
   dotspinner: ({ size } = {}) =>
     j(cls.dotspinner, size === 'sm' && cls.dotspinnerSm, size === 'lg' && cls.dotspinnerLg),
   dotbar: ({ indeterminate } = {}) => j(cls.dotbar, indeterminate && cls.dotbarIndeterminate),
-  modal: ({ drawer } = {}) => j(cls.modal, drawer && cls.modalDrawer),
+  modal: ({ drawer, open } = {}) => j(cls.modal, drawer && cls.modalDrawer, open && 'is-open'),
   tab: ({ active } = {}) => j(cls.tab, active && 'is-active'),
   avatar: ({ size } = {}) =>
     j(cls.avatar, size === 'sm' && cls.avatarSm, size === 'lg' && cls.avatarLg),
   prose: ({ compact } = {}) => j(cls.prose, compact && cls.proseCompact),
-  container: ({ narrow } = {}) => j(cls.container, narrow && cls.containerNarrow),
+  container: ({ narrow, wide } = {}) =>
+    j(cls.container, narrow && cls.containerNarrow, wide && cls.containerWide),
   tag: ({ accent } = {}) => j(cls.tag, accent && cls.tagAccent),
 };
 

package/css/app.css

@@ -111,6 +111,22 @@
   padding-block-start: var(--space-sm);
 }
 
+/* Account / identity slot — signed-in user + sign-out. A framework-
+   blessed home for what every shell otherwise hand-rolls. Pinned to the
+   rail end like __foot, but it stays visible when the rail collapses to
+   a horizontal bar on mobile (sign-out must not vanish). */
+.ui-app-rail__account {
+  align-items: center;
+  display: flex;
+  gap: var(--space-xs);
+  margin-block-start: auto;
+  padding-block-start: var(--space-sm);
+}
+
+.ui-app-rail__account + .ui-app-rail__foot {
+  margin-block-start: 0;
+}
+
 /* --- Main column --- */
 
 .ui-app-main {
@@ -196,77 +212,23 @@
   text-transform: uppercase;
 }
 
-.ui-app-panel__head p,
-.ui-app-empty-state p {
+.ui-app-panel__head p {
   color: var(--text-dim);
   margin: 0.3rem 0 0;
 }
 
-/* --- Metric tiles --- */
-
-.ui-app-metrics {
-  display: grid;
-  gap: var(--space-md);
-  grid-template-columns: repeat(auto-fit, minmax(11rem, 1fr));
-}
+/* --- Metric tiles ---
+   The metric primitive itself is shell-agnostic and now lives in
+   primitives.css as `.ui-stat` / `.ui-statgrid`; `.ui-app-metric*` and
+   `.ui-app-metrics` remain as permanent admin-shell aliases (grouped on
+   the canonical rules there — identical output). Nothing app-specific
+   left to define here. */
 
-/* Inside an opt-in .ui-cq container, collapse to one column when the
-   container (not the viewport) is narrow — keeps metric tiles usable
-   in a slim panel. Inert without .ui-cq, so baselines are unaffected. */
-@container bronto (max-width: 30rem) {
-  .ui-app-metrics {
-    grid-template-columns: 1fr;
-  }
-}
-
-.ui-app-metric {
-  background: var(--panel);
-  border: 1px solid var(--line);
-  border-radius: var(--radius-md);
-  display: grid;
-  gap: 0.4rem;
-  padding: var(--space-md);
-}
-
-.ui-app-metric__label {
-  color: var(--text-dim);
-  font-family: var(--mono);
-  font-size: var(--text-2xs);
-  letter-spacing: var(--tracking-wide);
-  text-transform: uppercase;
-}
-
-.ui-app-metric__value {
-  color: var(--text);
-  font-family: var(--display);
-  font-size: 1.9rem;
-  font-variant-numeric: tabular-nums;
-  letter-spacing: 0.01em;
-  line-height: 1;
-}
-
-.ui-app-metric__delta {
-  font-family: var(--mono);
-  font-size: var(--text-xs);
-}
-
-.ui-app-metric__delta.is-pos {
-  color: var(--success);
-}
-
-.ui-app-metric__delta.is-neg {
-  color: var(--danger);
-}
-
-/* --- Empty state --- */
-
-.ui-app-empty-state {
-  border: 1px dashed var(--line-strong);
-  border-radius: var(--radius-md);
-  color: var(--text-dim);
-  padding: var(--space-lg);
-  text-align: center;
-}
+/* --- Empty state ---
+   The empty-state primitive is shell-agnostic and now lives in
+   primitives.css as `.ui-empty-state`; `.ui-app-empty-state` remains a
+   permanent admin-shell alias (grouped on the canonical rules there —
+   identical output). Nothing app-specific left to define here. */
 
 /* --- Mobile rail collapse --- */
 

package/css/dots.css

@@ -44,6 +44,30 @@
   inline-size: 100%;
 }
 
+/* Data-bound dot matrix — a grid of state cells (activity / heatmap),
+   the on-brand counterpart to the decorative .ui-dotgrid background.
+   This is the grid + cell tones only; the data→cell mapping is the
+   consumer's. Tune density via --dotmatrix-cols / --dotmatrix-gap. */
+.ui-dotmatrix {
+  display: grid;
+  gap: var(--dotmatrix-gap, 0.5rem);
+  grid-template-columns: repeat(var(--dotmatrix-cols, 12), minmax(0, 1fr));
+}
+
+.ui-dotmatrix__cell {
+  aspect-ratio: 1;
+  background: var(--field-dot);
+  border-radius: 50%;
+}
+
+.ui-dotmatrix__cell--hot {
+  background: var(--field-dot-hot);
+}
+
+.ui-dotmatrix__cell--accent {
+  background: var(--field-dot-accent);
+}
+
 /* Status dot — the glyph-style state indicator. */
 .ui-dot {
   background: var(--text-dim);

package/css/overlay.css

@@ -31,6 +31,16 @@
   grid-template-rows: auto 1fr auto;
 }
 
+/* Controlled (non-<dialog>) usage. A portal/React modal that can't be a
+   native <dialog> wears the same skin + open layout via `.is-open`.
+   Backdrop, top-layer stacking and focus-trapping are then the
+   consumer's responsibility (the native <dialog> path gets them free). */
+.ui-modal.is-open {
+  animation: uiToastIn var(--duration-base) var(--ease-spring) both;
+  display: grid;
+  grid-template-rows: auto 1fr auto;
+}
+
 .ui-modal__head {
   align-items: flex-start;
   border-block-end: 1px solid var(--line);