@kerfjs/ui 5.0.0-beta.10 → 5.0.0-beta.101

package/docs/writing.md

@@ -0,0 +1,152 @@
+# Writing interface copy
+
+Kerf UI follows Apple's capitalization conventions for interface text.
+Apple's _Writing_ guidance asks for one style per UI element type, applied
+consistently, and its element guidance assigns those styles. This page is the
+package default, so every Kerf application, demo, and recipe uses the same
+rule. An application may replace it only through a written, product-wide
+style. It should never vary from one screen to the next.
+
+## Capitalization
+
+**Names are title style. Descriptions are sentence style.** Text that names a
+command, control, view, or field uses title style ("Save Draft", "Workspace
+Settings", "Release Date"). Text that describes, explains, reports, or asks
+uses sentence style ("Changes sync when you reconnect").
+
+| Element                                                                                             | Style                        | Examples                                               |
+| --------------------------------------------------------------------------------------------------- | ---------------------------- | ------------------------------------------------------ |
+| Buttons, split-button and toolbar actions, link-style commands                                      | Title                        | Save Draft, Add to Favorites, Don’t Save, Log In       |
+| Menu items, menu group headings, popup-menu triggers                                                | Title                        | Copy Reference, Sort By, Recently Updated, New Folder… |
+| Segmented-control segments, `Select` and pop-up choices, tabs                                       | Title                        | List View, Last 30 Days, In Review                     |
+| Page, view, pane, dialog, and toolbar titles (`ToolbarText` titles), back labels                    | Title                        | Workspace Settings, Back to Inbox                      |
+| Group and list headers (`ListHeader`), table column headings                                        | Title                        | Saved Projects, Needs Attention, Last Modified         |
+| Catalog example and stack labels (`CatalogExample`, `CatalogExampleStack`)                          | Title                        | Heading Identity Stays Whole, Icon Trigger in a Group  |
+| Content item titles: the name an item or card shows                                                 | Title                        | Build Output, Work Area, Unsaved Changes               |
+| Field labels (`FieldLabel`, a field's `label`)                                                      | Title                        | Project Name, Release Date                             |
+| Region and landmark names (accessible names of panes, toolbars, groups, lists, tab bars)            | Title                        | Ticket Workbench, View Actions, Open Documents         |
+| Accessible names of icon-only controls                                                              | Title                        | More Actions, Clear Search                             |
+| `EmptyState`, `StateBanner`, alert, and notification titles that are fragments                      | Title, no ending punctuation | No Release Tasks, Migration Needs Review               |
+| The same titles written as complete sentences                                                       | Sentence, with punctuation   | Release tasks could not be refreshed.                  |
+| Checkbox, switch, and radio option text                                                             | Sentence                     | Show hidden files, Notify me about replies             |
+| Body copy, `description`, `detail`, hints, empty-state and banner detail, dialog and alert messages | Sentence, with punctuation   | Changes sync when you reconnect.                       |
+| Tooltips and help text                                                                              | Sentence                     | Copy the link to this ticket                           |
+| Placeholders                                                                                        | Sentence                     | Search tickets                                         |
+| Status lines, counts, and timestamps (`ToolbarText` status, `Badge`, `CornerStatus`)                | Sentence                     | Saved just now, 3 of 12 updated                        |
+| Progress labels (`LoadingSpinner` and `Skeleton` `label`): the operation under way                  | Sentence, trailing ellipsis  | Loading preview…, Refreshing release tasks…            |
+
+A name that a component composes into a longer label is a name too, so pass
+it in title style. A panel toolbar's `toggle: { action, name }` labels the
+toggle group with `name` and completes "Show …" / "Hide …" with it:
+`name: "Navigator"` gives "Show Navigator". Kerf UI never recapitalizes it.
+
+Data is never recapitalized. Names that a person or a system supplies keep
+their own spelling: file names, ticket titles, user names, and tags. So do
+code identifiers shown as text, such as a prop value a specimen is labeled
+with (`danger`, `transparent`). A content
+item that shows such data (a ticket subject, a message) keeps it as written;
+only a title the interface itself names is title style. `ContentItem`'s own
+`title` prop is a native tooltip, so it is sentence style. Keep a content
+item's `ariaLabel` equal to its visible title.
+
+### Title-style rules
+
+From the [Apple Style Guide](https://support.apple.com/guide/applestyleguide/c-apsgb744e4a3/web)
+(_capitalization_):
+
+- **Capitalize** the first and last word, whatever their part of speech.
+- **Capitalize** nouns, pronouns, verbs, adjectives, and adverbs, however
+  short: It, This, Your, Is, Are, Be.
+- **Capitalize** subordinating conjunctions such as If, and prepositions of
+  five letters or more: About, Between, Through.
+- **Capitalize** a preposition of any length that belongs to a phrasal verb
+  or acts as another part of speech: Start Up the Computer, Turn On, Log In to
+  the Server.
+- **Capitalize** the second word of a hyphenated compound: High-Level Events,
+  Pop-Up Menu. Built-in and Plug-in are the exceptions.
+- **Keep lowercase**:
+  - articles (a, an, the), unless one is the first word or follows a colon;
+  - coordinating conjunctions (and, but, or, nor, for, yet, so);
+  - _to_ in an infinitive (How to Start Your Computer);
+  - _as_ (Export a Document as a PDF);
+  - prepositions of four letters or fewer (at, by, for, from, in, into, of,
+    off, on, onto, out, over, to, up, with).
+- **Keep the brand's own spelling** for words that always start lowercase,
+  such as iPad, iOS, and macOS.
+
+### Sentence-style rules
+
+Capitalize the first word and proper nouns or adjectives only. End a complete
+sentence with punctuation. Leave a fragment without ending punctuation.
+Tooltips may omit the final period.
+
+### Related conventions
+
+- An ellipsis (…) ends a command or menu item that needs more input before it
+  acts: New Ticket…, Save As…. The dialog it opens repeats the command as its
+  title, without the ellipsis.
+- Label an action with its result. Prefer a verb: Publish Update, not OK.
+- Keep a control's accessible name equal to its visible label, or starting
+  with it.
+
+## Diagnostics
+
+`kerf-ui-doctor` reports `KUI-D040` (warning) when a string or template
+literal passed to a known title-style prop leaves a word lowercase that title
+style capitalizes. In a template literal it judges only the static words:
+`` `Edit ${name} shortcut` `` should be `` `Edit ${name} Shortcut` ``, and the
+interpolated value keeps its own spelling. The covered props are:
+
+- `ToolbarText` `text` when the text is a title: it has `headingLevel`, a
+  large size, or sits in a toolbar or panel `title`, `header`, or (unless small) `leading` slot;
+- `ListHeader`, `ListActionRow`, `SplitButton`, and `Combobox` `label`;
+- `CatalogExample` and `CatalogExampleStack` `label`;
+- `EmptyState` and `StateBanner` `title`;
+- `PopupMenu` `text` and item and heading labels, including submenus;
+- `SegmentedControl`, `Select`, and `TabNavigator` choice and tab labels;
+- `NavStack` view titles and `backText`, and `SplitView` `backLabel`;
+- `FieldLabel` text and the text of a `button` or `wa-button`;
+- the `name` of a panel toolbar's `toggle: { action, name }`;
+- region and landmark names: the `label` of `Pane`, `Workbench`, `Toolbar`,
+  `ToolbarControlGroup`, `TabBar`, `NavStack`, `CollapsiblePanel`,
+  `FloatingToolbar`, and `ResizableRegion`, the `ariaLabel` of `SunkenPanel`
+  and `List`, a `Pane`'s `contentLabel`, the panel, toolbar, and pane labels
+  inside `Workbench`, `CollapsiblePanel`, and `NavStack` configuration, and
+  the `aria-label` of a landmark element (`section`, `nav`, `aside`, `main`,
+  `header`, `footer`, `form`, `search`) or landmark role;
+- the `label` of a raw `wa-input`, `wa-select`, `wa-textarea`, or
+  `wa-radio-group`;
+- the accessible names of icon-only controls: `IconButton` and
+  `IconToggleButton` `label`, `PopupMenu` `label`, `SplitButton`
+  `optionsLabel`, `TokenSearchField` `clearLabel`, and the `aria-label` of a
+  `button` or `wa-button` whose only content is an icon.
+
+The check never judges sentence-style surfaces (including `wa-checkbox`,
+`wa-switch`, and `wa-radio` option text and the `LoadingSpinner` and
+`Skeleton` status labels), interpolated or other dynamic values, or text
+ending with `.`, `!`, or `?`. It skips a word joined to an interpolation, tokens containing digits, code, or paths, and
+lowercase-led brands such as iOS. It does not report capitalized short words,
+because Apple capitalizes a phrasal verb's particle. Suppress `KUI-D040` for a
+lowercase brand or product name. See [the doctor](./ui-doctor.md).
+
+## Sources
+
+- Apple Human Interface Guidelines,
+  [Writing](https://developer.apple.com/design/human-interface-guidelines/writing):
+  choose a capitalization style for each element type and use it consistently.
+- [Menus](https://developer.apple.com/design/human-interface-guidelines/menus)
+  and [The menu bar](https://developer.apple.com/design/human-interface-guidelines/the-menu-bar):
+  menu items and multi-word menu titles use title-style capitalization.
+- [Alerts](https://developer.apple.com/design/human-interface-guidelines/alerts)
+  and [Notifications](https://developer.apple.com/design/human-interface-guidelines/notifications):
+  a fragment title uses title style. A complete-sentence title and the
+  message use sentence style with punctuation.
+- [Offering help](https://developer.apple.com/design/human-interface-guidelines/offering-help):
+  tooltips use sentence case.
+- The archived OS X Human Interface Guidelines, _Use the Right Capitalization
+  Style in Labels and Text_. Title style covers menu titles and items, push
+  buttons, toolbar item labels, and labels that are not sentences, such as
+  group box and list headings. Sentence style covers checkbox and radio option
+  text and dialog messages.
+- [Apple Style Guide](https://support.apple.com/guide/applestyleguide/c-apsgb744e4a3/web),
+  _capitalization_: the title-style word rules above.

package/doctor/cli.mjs

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+
+import console from 'node:console';
+import { execFile } from 'node:child_process';
+import { writeFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import process from 'node:process';
+import { promisify } from 'node:util';
+
+import { formatUiDoctorText, runUiDoctor, UI_DOCTOR_EXIT } from './index.mjs';
+
+const execFileAsync = promisify(execFile);
+const args = process.argv.slice(2);
+const take = (name, repeat = false) => {
+  const values = [];
+  while (args.includes(name)) {
+    const index = args.indexOf(name);
+    const value = args[index + 1];
+    if (!value || value.startsWith('--'))
+      throw new Error(`${name} requires a value.`);
+    args.splice(index, 2);
+    values.push(value);
+    if (!repeat) break;
+  }
+  return repeat ? values : values[0];
+};
+
+async function changedPaths(root) {
+  const { stdout: tracked } = await execFileAsync(
+    'git',
+    ['diff', '--name-only', '--diff-filter=ACMR', 'HEAD', '--'],
+    { cwd: root },
+  );
+  const { stdout: untracked } = await execFileAsync(
+    'git',
+    ['ls-files', '--others', '--exclude-standard'],
+    { cwd: root },
+  );
+  return [
+    ...new Set(`${tracked}\n${untracked}`.split(/\r?\n/).filter(Boolean)),
+  ].sort();
+}
+
+try {
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log(`Usage: kerf-ui-doctor [--full | --changed] [options]
+
+Options:
+  --root <path>          Workspace root (default: current directory)
+  --package <name|path>  Select one workspace package
+  --path <path>          Restrict changed mode (repeatable)
+  --config <path>        Doctor config (default: .kerf-ui-doctor.json)
+  --browser-url <url>    Explicitly enable browser evaluation
+  --browser <list>       Comma-separated chromium,firefox,webkit
+  --eslint <preset>      recommended-ui or strict-ui
+  --format <format>      text or json (default: text)
+  --fail-on <severity>   error, review, or warning (default: error)
+  --output <path>        Also write the merged report
+  --no-cache             Disable the content-addressed cache
+
+Exit codes: 0 clean, 1 findings, 2 configuration/tool failure, 130 cancelled.`);
+    process.exit(0);
+  }
+  const root = resolve(take('--root') ?? process.cwd());
+  const packageSelector = take('--package');
+  const explicitPaths = take('--path', true);
+  const configPath = take('--config');
+  const url = take('--browser-url');
+  const browserList = take('--browser');
+  const eslintConfig = take('--eslint') ?? 'recommended-ui';
+  const format = take('--format') ?? 'text';
+  const failOn = take('--fail-on');
+  const output = take('--output');
+  const full = args.includes('--full');
+  const changed = args.includes('--changed');
+  const noCache = args.includes('--no-cache');
+  const known = new Set(['--full', '--changed', '--no-cache']);
+  const unknown = args.filter((item) => !known.has(item));
+  if (unknown.length)
+    throw new Error(`Unknown arguments: ${unknown.join(' ')}`);
+  if (full && changed)
+    throw new Error('--full and --changed are mutually exclusive.');
+  if (!['text', 'json'].includes(format))
+    throw new Error('--format must be text or json.');
+  if (failOn && !['error', 'review', 'warning'].includes(failOn))
+    throw new Error('--fail-on must be error, review, or warning.');
+  if (!['recommended-ui', 'strict-ui'].includes(eslintConfig))
+    throw new Error('--eslint must be recommended-ui or strict-ui.');
+  const abort = new globalThis.AbortController();
+  process.once('SIGINT', () => abort.abort());
+  const paths =
+    changed && !explicitPaths.length ? await changedPaths(root) : explicitPaths;
+  const report = await runUiDoctor({
+    root,
+    package: packageSelector,
+    mode: changed ? 'changed' : full ? 'full' : undefined,
+    paths,
+    configPath,
+    cache: !noCache,
+    signal: abort.signal,
+    eslintConfig,
+    failOn,
+    browser: url
+      ? { url, browsers: browserList?.split(',').map((item) => item.trim()) }
+      : undefined,
+  });
+  const rendered =
+    format === 'json'
+      ? JSON.stringify(report, null, 2)
+      : formatUiDoctorText(report);
+  if (output) await writeFile(resolve(root, output), `${rendered}\n`);
+  else console.log(rendered);
+  process.exitCode = report.exitCode;
+} catch (error) {
+  console.error(`kerf-ui-doctor: ${error.message}`);
+  process.exitCode =
+    process.exitCode === UI_DOCTOR_EXIT.cancelled
+      ? process.exitCode
+      : UI_DOCTOR_EXIT.configuration;
+}