@apliteni/apliteni-ui 0.11.1 → 0.12.0

package/README.md

@@ -31,6 +31,12 @@ as the vanilla kit, so the two layers can't drift.
 **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.
+
 ## Install
 
 Published on the **public npm registry** — no scope config, no token:

package/package.json

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

package/react/dist/index.css

@@ -59,7 +59,6 @@
   border-radius: 4px;
 }
 .rx-caret {
-  opacity: .5;
   margin-left: 2px;
 }
 .rx-pager {

package/src/assets/icons.js

@@ -6,7 +6,29 @@
 //
 // 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.
+//
+// ---- Adding a glyph -------------------------------------------------------
+//
+// NAME it for what it depicts, not for the one place it is used: `trash`, not
+// `deleteWorkspace`. camelCase, and a modifier follows its noun — `circleX`,
+// `eyeOff`, `trendingUp` — so the family sorts together. A name is taken once;
+// a second declaration of one is a gate failure, not a merge conflict.
+//
+// GROUP it by what it depicts, again rather than by caller. `chart` lives in
+// DATA because it draws data, even when a comms panel is what renders it. If
+// two groups both look right, the glyph belongs to the one whose other members
+// it would sit beside in the catalogue. Groups are not tags: exactly one.
+//
+// PROVENANCE: the path comes from Lucide, unmodified, at the 24×24 / 1.7 house
+// stroke — that is what keeps the set looking like one hand. Say which Lucide
+// name it came from in the commit if the two differ. A hand-drawn path needs a
+// reason in the commit message, because the next person cannot tell one from a
+// traced one by looking.
+//
+// The gates: src/assets/icons.test.js holds one-group-per-glyph and the
+// emitter's numbers, and stories/guidelines/iconography.test.js holds the
+// icon-only list below. The written rules are on Guidelines / Iconography.
 
 const NAV = {
   chevronDown: '<path d="M6 9l6 6 6-6" stroke-linecap="round" stroke-linejoin="round"/>',
@@ -101,9 +123,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 +159,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/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,
@@ -93,8 +97,14 @@ export function segmented({ options = [], active = 0, size, block, name = 'seg',
 }
 
 // ---- Accent picker -------------------------------------------------------
+// Each swatch is made of the tokens its accent selects: it fades from the next
+// distinct step up that accent's dark ramp down to dark --accent. Most accents
+// land on --purple-light; Nebula's is its own --accent since #157, so it walks
+// on to --purple-mid. site/chrome.mjs and site/index.html hand-keep the same
+// four strings and must change with these. Held by stories/accent-swatch.test.js,
+// which derives both sides rather than restating them. See issue #190.
 const ACCENT_SWATCH = {
-  default: 'linear-gradient(135deg,#9b5dff,#6a2dcc)',
+  default: 'linear-gradient(135deg,#bd8cff,#b479ff)',
   phoenix: 'linear-gradient(135deg,#ff8a5c,#ff6a3d)',
   ocean: 'linear-gradient(135deg,#5ab0ff,#3b9dff)',
   emerald: 'linear-gradient(135deg,#3ad9a0,#16c98a)',
@@ -211,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/styles/callout.css

@@ -29,7 +29,7 @@
 /* ----------------------------------------------------------------------------
  * Toast — a floating, dismissible notification.
  * A status (colour) × style (surface) matrix, entirely token-driven:
- *   status  success · danger · warn · info · neutral  → sets --toast-accent/-glow/-on/-solid
+ *   status  success · danger · warn · info · neutral  → sets --toast-accent/-action-ink/-glow/-on/-solid
  *   style   soft (tinted) · solid (filled) · outline (bordered)
  * -------------------------------------------------------------------------- */
 .ui-toast {
@@ -51,12 +51,21 @@
    --toast-accent is the status as a line or a small mark, --toast-glow its wash,
    --toast-on the glyph ink on the accent circle. --toast-solid is separate on
    purpose: a full fill is a different job from a 22px circle, and it is chosen
-   as a PAIR with --signal-solid-ink rather than against a global. See #149. */
-.ui-toast--success { --toast-accent: var(--green); --toast-glow: var(--glow-green); --toast-on: var(--signal-contrast); --toast-solid: var(--signal-solid-success); }
-.ui-toast--danger  { --toast-accent: var(--pink);  --toast-glow: var(--glow-pink);  --toast-on: var(--danger-contrast); --toast-solid: var(--signal-solid-danger); }
-.ui-toast--warn    { --toast-accent: var(--amber); --toast-glow: color-mix(in srgb, var(--amber) 14%, transparent); --toast-on: var(--signal-contrast); --toast-solid: var(--signal-solid-warn); }
-.ui-toast--info    { --toast-accent: var(--cyan);  --toast-glow: var(--glow-cyan);  --toast-on: var(--signal-contrast); --toast-solid: var(--signal-solid-info); }
-.ui-toast--neutral { --toast-accent: var(--muted); --toast-glow: var(--surface-2); --toast-on: var(--strong); --toast-solid: var(--signal-solid-neutral); }
+   as a PAIR with --signal-solid-ink rather than against a global. See #149.
+
+   --toast-action-ink is separate from --toast-accent for the same reason the
+   fill is: the accent is a graphic colour, sized for a 3px rule and a 22px
+   circle, and in the light theme it is not a colour text can be set in. The
+   trailing action is the one part of a toast that is BOTH the status colour and
+   a piece of text, so it takes the chip inks, which are the text-grade version
+   of the same five statuses. In the dark theme the two are the same value by
+   construction — --chip-success-ink IS --green there — so this splits the light
+   theme apart and leaves the dark one exactly as it was. */
+.ui-toast--success { --toast-accent: var(--green); --toast-action-ink: var(--chip-success-ink); --toast-glow: var(--glow-green); --toast-on: var(--signal-contrast); --toast-solid: var(--signal-solid-success); }
+.ui-toast--danger  { --toast-accent: var(--pink);  --toast-action-ink: var(--chip-danger-ink);  --toast-glow: var(--glow-pink);  --toast-on: var(--danger-contrast); --toast-solid: var(--signal-solid-danger); }
+.ui-toast--warn    { --toast-accent: var(--amber); --toast-action-ink: var(--chip-warn-ink);    --toast-glow: color-mix(in srgb, var(--amber) 14%, transparent); --toast-on: var(--signal-contrast); --toast-solid: var(--signal-solid-warn); }
+.ui-toast--info    { --toast-accent: var(--cyan);  --toast-action-ink: var(--chip-info-ink);    --toast-glow: var(--glow-cyan);  --toast-on: var(--signal-contrast); --toast-solid: var(--signal-solid-info); }
+.ui-toast--neutral { --toast-accent: var(--muted); --toast-action-ink: var(--muted);            --toast-glow: var(--surface-2); --toast-on: var(--strong); --toast-solid: var(--signal-solid-neutral); }
 
 /* left status marker (soft + outline; solid is already a full fill) */
 .ui-toast--soft::before,
@@ -71,9 +80,16 @@
 .ui-toast__title { font-weight: var(--weight-medium); color: var(--strong); }
 .ui-toast__text { color: var(--dim); }
 
-/* trailing action ("Undo" / "Retry") */
-.ui-toast__action { flex: none; align-self: center; background: none; border: 0; padding: 4px 9px; border-radius: var(--radius-xs); font: inherit; font-weight: var(--weight-medium); color: var(--toast-accent); cursor: pointer; }
-.ui-toast__action:hover { background: color-mix(in srgb, var(--toast-accent) 14%, transparent); }
+/* trailing action ("Undo" / "Retry") — status-coloured TEXT, so it takes the
+   text-grade ink rather than the accent.
+   The hover wash is the page background rather than the accent again: a second
+   accent tint on an already accent-tinted ground moved the ground TOWARDS the
+   ink and took every soft pair below the floor. --bg is white in the light theme
+   and near-black in the dark one, so one expression lightens the ground where
+   the ink is dark and darkens it where the ink is bright — the hovered pair is
+   at or above the resting pair in both. */
+.ui-toast__action { flex: none; align-self: center; background: none; border: 0; padding: 4px 9px; border-radius: var(--radius-xs); font: inherit; font-weight: var(--weight-medium); color: var(--toast-action-ink); cursor: pointer; }
+.ui-toast__action:hover { background: color-mix(in srgb, var(--bg) 55%, transparent); }
 
 .ui-toast__close { flex: none; align-self: flex-start; background: none; border: 0; color: var(--muted); cursor: pointer; padding: 2px; display: grid; place-items: center; }
 .ui-toast__close svg { width: 15px; height: 15px; stroke: currentColor; fill: none; stroke-width: 1.8; }
@@ -108,7 +124,10 @@
 .ui-toast--solid .ui-toast__text { color: color-mix(in srgb, var(--toast-ink) 90%, transparent); }
 .ui-toast--solid .ui-toast__icon { background: color-mix(in srgb, var(--toast-ink) 22%, transparent); color: var(--toast-ink); }
 .ui-toast--solid .ui-toast__action { color: var(--toast-ink); }
-.ui-toast--solid .ui-toast__action:hover { background: color-mix(in srgb, var(--toast-ink) 18%, transparent); }
+/* Hover darkens the FILL rather than lightening the ink. Washing the ink over
+   itself was the one surface #149 did not reach, and it worked against the pair
+   it was drawn from: it pulled the fill towards the ink it has to clear. */
+.ui-toast--solid .ui-toast__action:hover { background: color-mix(in srgb, var(--signal-contrast) 14%, transparent); }
 .ui-toast--solid .ui-toast__close { color: color-mix(in srgb, var(--toast-ink) 68%, transparent); }
 .ui-toast--solid .ui-toast__close:hover { color: var(--toast-ink); }
 .ui-toast--solid .ui-toast__timer { background: color-mix(in srgb, var(--toast-ink) 55%, transparent); }