@apliteni/apliteni-ui 0.87.0 → 0.89.0

package/guidelines/button-labels.md

@@ -0,0 +1,35 @@
+# Button labels
+
+## Keep the words
+
+<!-- rule: words-first -->
+
+**Rule:** Give every button words, and add a glyph only to help those words.
+
+**Do:** Export, Rename and Share, named at rest.
+
+**Don't:** The same three, each name waiting on a hover a finger never performs.
+
+## Let the glyph repeat the verb
+
+<!-- rule: glyph-repeats-the-verb -->
+
+**Rule:** Add a glyph beside a label only when it depicts that label’s action, and treat every button in a row the same way.
+
+**Except:** A dismissing action beside a committing one is not a peer, and stays plain.
+
+**Do:** The arrow downloads, the sheets copy.
+
+**Don't:** A table is what is exported, not the export, and the plain neighbour reads as lesser.
+
+## Earn a wordless button
+
+<!-- rule: wordless-earns-it -->
+
+**Rule:** Drop a button’s words only when its glyph is learned everywhere, its action is on the closed list, and its name is left to assistive technology and a hover title.
+
+**Except:** [Icon-only controls](https://ui.apli.tech/storybook/?path=/story/guidelines-iconography--iconography) is the list, and it grows by decision. The folded rail shows its names beside the glyphs instead, so those carry no title.
+
+**Do:** Overflow is on that list; the funnel is not.
+
+**Don't:** A funnel could filter, sort or export, and the cog gave up the word that said which.

package/guidelines/iconography.md

@@ -8,7 +8,7 @@
 
 **Why:** Without a legend, readers need labels for unfamiliar glyphs.
 
-**Except:** The list grows by decision, not review debate. Today: `x` (close or dismiss), `copy` (copy to clipboard), `moreHorizontal` (overflow menu), `moreVertical` (overflow menu), `chevronDown` (expand or collapse), `chevronUp` (expand or collapse), and the shell’s theme toggle, sidebar toggle and collapsed-rail links.
+**Except:** The list grows by decision, not review debate, and [Earn a wordless button](https://ui.apli.tech/storybook/?path=/story/guidelines-button-labels--button-labels) states the three tests an entry passes. Today: `x` (close or dismiss), `copy` (copy to clipboard), `moreHorizontal` (overflow menu), `moreVertical` (overflow menu), `chevronDown` (expand or collapse), `chevronUp` (expand or collapse). The shell’s own chrome — theme toggle, sidebar toggle, collapsed-rail links — is wordless by a separate decision, not by passing those tests.
 
 **Do:** Show an overflow menu without words; keep the Settings label.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apliteni/apliteni-ui",
-  "version": "0.87.0",
+  "version": "0.89.0",
   "workspaces": [
     "react"
   ],
@@ -57,6 +57,7 @@
     "build": "npm run build --workspace react",
     "prepare": "npm run build",
     "test": "for d in src stories site scripts; do [ -d \"$d\" ] || { echo \"npm test: no such directory: $d\" >&2; exit 1; }; done; node --test --test-reporter=spec --test-reporter-destination=stdout --test-reporter=./scripts/slow-tests.mjs --test-reporter-destination=stdout 'src/**/*.test.js' 'stories/**/*.test.js' 'site/**/*.test.js' 'scripts/**/*.test.js'",
+    "check:words": "node scripts/word-budget.mjs",
     "tokens:sync": "node scripts/sync-brand-tokens.mjs",
     "tokens:check": "node scripts/sync-brand-tokens.mjs --check",
     "tokens:drift": "node scripts/brand-drift.mjs"

package/react/README.md

@@ -515,11 +515,12 @@ instead, and the word goes to the track's accessible name. The file reads as a
 stack: the name on top with the actions at its end, the size — or the failure
 message — under it, and the track the full width below. No tier takes a second
 line. The name truncates its stem and keeps its extension, with the whole name in
-a `title`, and nothing is hidden or moved at any width. `Remove` is the icon-only
-`x`, named by `removeLabel`; `Retry` keeps its word. Both appear only when you
-handle them. Children render above the row, inside the region the target covers;
-pass `dragging` to drive that target from a parent. `accept` filters the system
-picker only — validate type and size yourself.
+a `title`, and nothing is hidden or moved at any width. `Remove` is the kit's
+small text button, worded by `removeLabel`; `Retry` keeps its word beside a
+glyph. Both appear only when you handle them. Children render above the row,
+inside the region the target covers; pass `dragging` to drive that target from
+a parent. `accept` filters the system picker only — validate type and size
+yourself.
 
 Use `Field` when an existing labelled control needs the kit frame. Spread its
 render-prop attributes onto one labelable control, and apply the existing control

package/react/dist/index.d.ts

@@ -698,7 +698,7 @@ type FileDropProps = {
     accept?: string;
     /** The words on the drop target. */
     dropLabel?: string;
-    /** Names the icon-only remove button; it carries no visible word. */
+    /** The word on the remove button. */
     removeLabel?: string;
     retryLabel?: string;
     /** The file the consumer is holding. Left out, the row is at rest. */

package/react/dist/index.js

@@ -2871,7 +2871,7 @@ function FileDrop({
   note,
   accept,
   dropLabel = "Drop to upload",
-  removeLabel = "Remove file",
+  removeLabel = "Remove",
   retryLabel = "Retry",
   file,
   dragging,
@@ -2928,11 +2928,9 @@ function FileDrop({
                   {
                     variant: "ghost",
                     size: "sm",
-                    icon: "x",
-                    iconOnly: true,
-                    "aria-label": removeLabel,
                     onClick: onRemove,
-                    disabled
+                    disabled,
+                    children: removeLabel
                   }
                 )
               ] })

package/src/assets/icons.js

@@ -150,6 +150,24 @@ export const iconNames = Object.keys(ICONS);
 // `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.
+//
+// Guidelines / Button labels states the three tests an entry passes: the glyph is
+// learned everywhere, its action is on this list, and the control keeps a name
+// assistive technology reads and a hover shows. button({ iconOnly }) writes
+// `aria-label` and `title` together, so a control built from the list below has
+// both — and neither reaches a keyboard reader who is not running one.
+//
+// The shell's folded-rail links and its sidebar toggle are the stated exception:
+// they show the label itself beside the glyph on hover and on focus, so they carry
+// no `title` — stories/apps/shell-rail.test.js holds them to that. They are a
+// separate decision about the shell's own chrome, not entries that passed the
+// tests above.
+//
+// `filter` — Lucide's funnel — fails the first test. Depicting a thing is not the
+// fault; `copy` is on this list and depicts one too. The kit reads the funnel alone
+// as not saying whether the control filters, sorts or exports — its own inference
+// from the sources in docs/specification.md, not a measured recognition finding.
+// See #565.
 export const iconOnlyAllowed = {
   x: 'close or dismiss',
   copy: 'copy to clipboard',
@@ -159,6 +177,21 @@ export const iconOnlyAllowed = {
   chevronUp: 'expand or collapse',
 };
 
+// The word a wordless control's name may open with. The list above says which
+// ACTIONS may drop their text; without this, a glyph on it carries any action a
+// caller likes — `copy` for Duplicate, `x` for Cancel — and the gate stays green,
+// which is what #566's review found. The opening word, not the whole name, so
+// "Copy project ID" is Copy naming what it copies.
+// stories/guidelines/iconography.test.js reads call sites against both maps.
+export const iconOnlyNames = {
+  x: ['close', 'dismiss'],
+  copy: ['copy'],
+  moreHorizontal: ['more'],
+  moreVertical: ['more'],
+  chevronDown: ['expand', 'collapse', 'show', 'hide'],
+  chevronUp: ['expand', 'collapse', 'show', 'hide'],
+};
+
 // What a glyph means when a component picks it for the reader rather than a
 // caller naming it. Two rules hold the map together:
 //

package/src/index.d.ts

@@ -45,6 +45,7 @@ export declare const SCORE: Record<'exact' | 'prefix' | 'wordStart' | 'contains'
 export declare const iconNames: string[];
 export declare const iconCategories: { name: string; names: string[] }[];
 export declare const iconOnlyAllowed: Record<string, string>;
+export declare const iconOnlyNames: Record<string, string[]>;
 export declare const iconMeanings: Record<string, string>;
 export declare const sun: string;
 export declare const moon: string;