@prongsjs/ui 0.2.0 → 0.3.0

package/dist/tooling/components.js

@@ -25,7 +25,7 @@ export const COMPONENT_DOCS = {
             { name: 'intent', type: 'TextIntent', description: 'What this text is for: `heading.*`, `text.*` or `feedback.*`.', required: true },
             {
                 name: 'as',
-                type: "'h1'…'h6' | 'p' | 'span' | 'div' | 'label'",
+                type: "'h1'…'h6' | 'p' | 'span' | 'div' | 'label' | 'dt' | 'dd'",
                 description: 'Changes the element for document structure only, like `as="label"` for a field label or `as="h2"` for a dialog title. The intent still decides the look.',
             },
             { name: 'htmlFor', type: 'string', description: 'With `as="label"`: the `id` of the field it labels.' },
@@ -50,6 +50,8 @@ export const COMPONENT_DOCS = {
             { name: 'label', type: 'string', description: 'The accessible name. Required when there is no visible text (an icon alone).' },
             { name: 'disabled', type: 'boolean', description: 'Turns it off. A disabled link loses its `href`.' },
             { name: 'type', type: "'button' | 'submit' | 'reset'", description: 'Buttons are `type="button"` unless the intent says otherwise (`action.submit` is `submit`).' },
+            { name: 'verb', type: 'string', description: 'The verb this action performs, for analytics: `verb="duplicate"` sets `data-verb`. The intent stays the same.' },
+            { name: 'tone', type: "'danger'", description: 'For an action that is destructive or hard to undo, like leaving a workspace. Sets `data-tone`; the intent styles it.' },
             VARS,
             UNSAFE,
         ],
@@ -64,11 +66,13 @@ export const COMPONENT_DOCS = {
         summary: 'What the user types or picks in a form. The intent decides the element (`<input>`, `<textarea>`, `<select>`) and sets `type`, `inputMode` and `autoComplete`.',
         layoutProps: true,
         props: [
-            { name: 'intent', type: 'FieldIntent', description: 'What is being entered: `field.email`, `field.password`, `field.multiline`...', required: true },
+            { name: 'intent', type: 'FieldIntent', description: 'What is being entered: `field.email`, `field.password`, `field.date`...', required: true },
             { name: 'label', type: 'ReactNode', description: 'The label. With it, Field renders the whole `layout.field`: label, field, hint and error, connected for screen readers.' },
             { name: 'hint', type: 'ReactNode', description: 'Help under the field (`text.caption`). Needs `label`.' },
             { name: 'error', type: 'ReactNode', description: 'What is wrong with the value (`feedback.error`). Marks the field invalid. Needs `label`.' },
             { name: 'rows', type: 'number', description: 'Height of a multiline field, in lines.' },
+            { name: 'revealed', type: 'boolean', description: 'For `field.password`: true while the password is shown as text.' },
+            { name: 'type', type: "'date' | 'time' | 'datetime-local'", description: 'For `field.date`: a time, or a date and time, instead of a date.' },
             { name: 'children', type: 'ReactNode', description: 'For select fields: the `<option>`s.' },
             { name: 'ref', type: 'Ref<HTMLInputElement>', description: 'Reaches the underlying element.' },
             UNSAFE,
@@ -122,7 +126,7 @@ export const COMPONENT_DOCS = {
         summary: 'Modal interruptions on the native `<dialog>`: focus stays inside, Escape closes it and the page behind is inert.',
         layoutProps: false,
         props: [
-            { name: 'intent', type: 'DialogIntent', description: '`dialog.task`, `dialog.confirm` or `dialog.reader`.', required: true },
+            { name: 'intent', type: 'DialogIntent', description: '`dialog.task`, `dialog.confirm`, `dialog.sheet`...', required: true },
             { name: 'open', type: 'boolean', description: 'Whether it is showing. You keep it in state.', required: true },
             { name: 'onClose', type: '() => void', description: 'Called on Escape, a click outside, or when it closes itself.', required: true },
             { name: 'label', type: 'string', description: 'The accessible name: usually the heading text.', required: true },
@@ -140,8 +144,9 @@ export const COMPONENT_DOCS = {
             { name: 'label', type: 'string', description: 'The accessible name: what it holds, like "Article actions".', required: true },
             { name: 'children', type: 'ReactNode', description: 'The content: `<Action>`s for a menu, choices for a picker, text for detail.' },
             { name: 'options', type: '{ value, label?, disabled? }[]', description: 'A picker’s choices as data, for lists from a database or a CMS. They render as a listbox (`role="option"`, `aria-selected`), announced like a native select.' },
-            { name: 'value', type: 'string | string[]', description: 'A picker’s choice: one value, or several when its intent picks many (`popover.picker.many`).' },
-            { name: 'onChange', type: '(value) => void', description: 'Called with the new choice, or with every picked value when its intent picks many.' },
+            { name: 'value', type: 'string | string[]', description: 'A picker’s choice: one value, or several with `multiple`.' },
+            { name: 'onChange', type: '(value) => void', description: 'Called with the new choice, or with every picked value with `multiple`.' },
+            { name: 'multiple', type: 'boolean', description: 'For `popover.picker`: any number of choices can be picked. It stays open while picking.' },
             { name: 'keepOpen', type: 'boolean', description: 'Stay open when something inside is pressed. Pickers that pick many stay open anyway.' },
             UNSAFE,
         ],

package/dist/tooling/spec.js

@@ -30,6 +30,7 @@ function arrangementOf(classes) {
     const width = has('mx-auto') ? list.find((name) => name.startsWith('max-w-')) : undefined;
     return [flow, gap, width && `centred ${width}`].filter(Boolean).join(', ');
 }
+const applies = (registry, g) => g.ids.every((id) => registry.has(id)) && !(g.without ?? []).some((id) => registry.has(id));
 const NESTING = [
     { ids: ['layout.form', 'layout.field', 'layout.actions'], text: '`layout.form` holds `layout.field`s, then one `layout.actions` with its buttons.' },
     {
@@ -42,7 +43,15 @@ const NESTING = [
         text: '`layout.table` is the `<table>`. Inside it write plain `<thead>`, `<tbody>`, `<tr>`, `<th scope="col">` and `<td>` with no classes; put `<Text>` and `<Action>` intents in the cells. When it has more columns than fit on a phone, wrap it in `<Layout intent="layout.scroller" tabIndex={0} aria-label="...">`.',
     },
     { ids: ['layout.shell', 'layout.aside', 'layout.page'], text: '`layout.shell` holds one `layout.aside` (the sidebar) and the `layout.page`.' },
-    { ids: ['layout.meta', 'text.meta'], text: '`layout.meta` holds `text.meta` facts (time, author, counts) about one item.' },
+    { ids: ['layout.group', 'text.meta'], text: 'A line of `text.meta` facts (time, author, counts) about one item sits in a `layout.group` with `flex-row`.' },
+    {
+        ids: ['layout.details', 'text.label'],
+        text: '`layout.details` (`<dl>`) holds one plain `<div>` per pair: a `<Text intent="text.label" as="dt">` and the value `as="dd"`.',
+    },
+    { ids: ['layout.intro', 'layout.section'], text: '`layout.intro` holds a section’s heading and lead, first in its `layout.section`, above the content it introduces.' },
+    { ids: ['layout.split'], text: '`layout.split` holds exactly two children, side by side on wider screens and stacked on phones.' },
+    { ids: ['layout.toast'], text: '`layout.toast` holds one `feedback.*` line and at most one `<Action>`, like Undo.' },
+    { ids: ['layout.empty'], text: '`layout.empty` holds an icon or image, a `heading.item`, a `text.caption` and the first action to take.' },
     { ids: ['layout.toolbar'], text: '`layout.toolbar` holds the controls for the content below it: filters, views, search, a refresh.' },
     { ids: ['layout.notice', 'action.dismiss'], text: '`layout.notice` holds one `feedback.*` message and an `action.dismiss`.' },
     { ids: ['layout.disclosure', 'text.summary'], text: '`layout.disclosure` (`<details>`) starts with one `text.summary` line, then the content it opens.' },
@@ -61,18 +70,51 @@ const EXAMPLES = [
     <Action intent="action.cancel" onClick={cancel}>Cancel</Action>
     <Action intent="action.save" type="submit">Save</Action>
   </Layout>
+</Layout>`,
+    },
+    {
+        title: 'A form with a label, a hint and an error',
+        ids: ['layout.form', 'layout.field', 'text.label', 'field.text', 'feedback.error', 'field.email', 'text.caption', 'layout.actions', 'action.cancel', 'action.submit'],
+        without: ['action.save'],
+        text: `<Layout intent="layout.form" onSubmit={save}>
+  <Field intent="field.text" label="Display name" error={nameError} value={name} onChange={(e) => setName(e.target.value)} />
+  <Field intent="field.email" label="Email" hint="Only used for signing in." />
+  <Layout intent="layout.actions">
+    <Action intent="action.cancel" onClick={cancel}>Cancel</Action>
+    <Action intent="action.submit" verb="save">Save</Action>
+  </Layout>
 </Layout>`,
     },
     {
         title: 'A list of items with facts and a row action',
-        ids: ['layout.list', 'layout.item', 'media.person', 'layout.group', 'heading.item', 'layout.meta', 'text.meta', 'action.remove'],
+        ids: ['layout.list', 'layout.item', 'media.person', 'layout.group', 'heading.item', 'text.meta', 'action.command'],
+        without: ['action.remove'],
         text: `<Layout intent="layout.list">
   {members.map((member) => (
     <Layout key={member.id} intent="layout.item" className="flex-row items-center">
       <Media intent="media.person" src={member.avatarUrl} alt={member.name} />
       <Layout intent="layout.group" className="flex-1">
         <Text intent="heading.item">{member.name}</Text>
-        <Layout intent="layout.meta">
+        <Layout intent="layout.group" className="flex-row flex-wrap">
+          <Text intent="text.meta">{member.role}</Text>
+          <Text intent="text.meta">Joined {member.joined}</Text>
+        </Layout>
+      </Layout>
+      <Action intent="action.command" verb="remove" tone="danger" onClick={() => remove(member.id)}>Remove</Action>
+    </Layout>
+  ))}
+</Layout>`,
+    },
+    {
+        title: 'A list of items with facts and a row action',
+        ids: ['layout.list', 'layout.item', 'media.person', 'layout.group', 'heading.item', 'text.meta', 'action.remove'],
+        text: `<Layout intent="layout.list">
+  {members.map((member) => (
+    <Layout key={member.id} intent="layout.item" className="flex-row items-center">
+      <Media intent="media.person" src={member.avatarUrl} alt={member.name} />
+      <Layout intent="layout.group" className="flex-1">
+        <Text intent="heading.item">{member.name}</Text>
+        <Layout intent="layout.group" className="flex-row flex-wrap">
           <Text intent="text.meta">{member.role}</Text>
           <Text intent="text.meta">Joined {member.joined}</Text>
         </Layout>
@@ -108,6 +150,57 @@ const EXAMPLES = [
     </Layout>
   </Layout>
 </Dialog>`,
+    },
+    {
+        title: 'A section with an introduction and a grid',
+        ids: ['layout.section', 'layout.intro', 'heading.section', 'text.lead', 'layout.collection', 'layout.panel'],
+        text: `<Layout intent="layout.section">
+  <Layout intent="layout.intro">
+    <Text intent="heading.section">Plans</Text>
+    <Text intent="text.lead">Start free and upgrade when your team grows.</Text>
+  </Layout>
+  <Layout intent="layout.collection">
+    {plans.map((plan) => (
+      <Layout key={plan.id} intent="layout.panel">…</Layout>
+    ))}
+  </Layout>
+</Layout>`,
+    },
+    {
+        title: 'Facts about one record, beside its image',
+        ids: ['layout.split', 'media.image', 'layout.details', 'text.label', 'text.body'],
+        text: `<Layout intent="layout.split">
+  <Media intent="media.image" src={order.image} alt={order.name} />
+  <Layout intent="layout.details">
+    <div>
+      <Text intent="text.label" as="dt">Ordered</Text>
+      <Text intent="text.body" as="dd">{order.date}</Text>
+    </div>
+    <div>
+      <Text intent="text.label" as="dt">Total</Text>
+      <Text intent="text.body" as="dd">{order.total}</Text>
+    </div>
+  </Layout>
+</Layout>`,
+    },
+    {
+        title: 'Loading, empty and a saved message',
+        ids: ['layout.loading', 'layout.empty', 'heading.item', 'text.caption', 'action.start', 'layout.toast', 'feedback.success', 'action.command'],
+        without: ['action.create'],
+        text: `{projects === undefined && <Layout intent="layout.loading" className="h-24" aria-busy="true" />}
+{projects?.length === 0 && (
+  <Layout intent="layout.empty">
+    <Text intent="heading.item">No projects yet</Text>
+    <Text intent="text.caption">A project holds your pages and who can edit them.</Text>
+    <Action intent="action.start" verb="create" href="/projects/new">Create project</Action>
+  </Layout>
+)}
+{saved && (
+  <Layout intent="layout.toast">
+    <Text intent="feedback.success">Your changes were saved.</Text>
+    <Action intent="action.command" verb="undo" onClick={undo}>Undo</Action>
+  </Layout>
+)}`,
     },
     {
         title: 'Loading, empty and a dismissible notice',
@@ -150,11 +243,11 @@ function componentProps() {
 }
 /** The examples whose intents all exist, for tests that check them against a registry. */
 export function specExamples(registry) {
-    return EXAMPLES.filter((e) => e.ids.every((id) => registry.has(id))).map((e) => ({ title: e.title, code: e.text }));
+    return EXAMPLES.filter((e) => applies(registry, e)).map((e) => ({ title: e.title, code: e.text }));
 }
 export function uiSpecSection(registry, context) {
     const from = context.componentsImport ?? './components/prongs';
-    const has = (g) => g.ids.every((id) => registry.has(id));
+    const has = (g) => applies(registry, g);
     const out = [
         '## UI rules',
         '',
@@ -260,8 +353,8 @@ export const UI_RULE_DOCS = [
         profile: 'ui',
         severity: 'error',
         summary: 'An intent rendered by the wrong component, like an action on `<Text>`.',
-        bad: '<Text intent="action.save">Save</Text>',
-        good: '<Action intent="action.save">Save</Action>',
+        bad: '<Text intent="action.submit">Save</Text>',
+        good: '<Action intent="action.submit">Save</Action>',
     },
     {
         id: 'leaf-classname',
@@ -276,7 +369,7 @@ export const UI_RULE_DOCS = [
         profile: 'ui',
         severity: 'error',
         summary: '`style` on a component that takes no style. An inline style overrides the intent just like a className.',
-        bad: '<Action intent="action.save" style={{ color: \'red\' }}>Save</Action>',
+        bad: '<Action intent="action.submit" style={{ color: \'red\' }}>Save</Action>',
         good: '<Action intent="action.delete">Delete</Action>',
     },
     {
@@ -314,8 +407,8 @@ export const UI_RULE_DOCS = [
         profile: 'ui',
         severity: 'warning',
         summary: 'An action whose handler, label or text points to a different intent, through the intents’ keywords.',
-        bad: '<Action intent="action.save" onClick={shareArticle}>Share</Action>',
-        good: '<Action intent="action.share" onClick={shareArticle}>Share</Action>',
+        bad: '<Action intent="action.delete" onClick={archiveProject}>Archive</Action>',
+        good: '<Action intent="action.command" verb="archive" onClick={archiveProject}>Archive</Action>',
     },
     {
         id: 'raw-look',
@@ -355,6 +448,6 @@ export const UI_RULE_DOCS = [
         severity: 'info',
         summary: 'An intent computed at runtime, so it could not be checked. A ternary of literals can be.',
         bad: '<Action intent={intentFor(state)}>…</Action>',
-        good: "<Action intent={following ? 'action.toggle' : 'action.add'}>…</Action>",
+        good: '<Action intent="action.toggle" pressed={following}>Follow</Action>',
     },
 ];

package/dist/vocabulary.js

@@ -19,10 +19,10 @@ export const COMPONENT_DOMAINS = {
 export const COMPONENT_NAMES = Object.keys(COMPONENT_DOMAINS);
 /** Elements an intent may choose through `binding.element`, per component. */
 export const ALLOWED_ELEMENTS = {
-    Text: ['h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'p', 'span', 'div', 'label', 'strong', 'em', 'small', 'blockquote', 'code', 'pre', 'summary'],
+    Text: ['h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'p', 'span', 'div', 'label', 'strong', 'em', 'small', 'blockquote', 'code', 'pre', 'summary', 'dt', 'dd'],
     Action: [],
     Field: ['input', 'textarea', 'select'],
-    Layout: ['div', 'main', 'section', 'article', 'aside', 'header', 'footer', 'nav', 'form', 'fieldset', 'ul', 'ol', 'li', 'hr', 'details', 'table', 'figure'],
+    Layout: ['div', 'main', 'section', 'article', 'aside', 'header', 'footer', 'nav', 'form', 'fieldset', 'ul', 'ol', 'li', 'dl', 'hr', 'details', 'table', 'figure'],
     /** Images by default; an intent can make it a frame that shows another page. */
     Media: ['iframe'],
     Dialog: [],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prongsjs/ui",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "The Prongs UI profile: intents that resolve to Tailwind classes, elements and ARIA roles, plus the tooling that checks how they are used.",
   "keywords": [
     "intents",
@@ -52,7 +52,7 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@prongsjs/core": "0.2.0"
+    "@prongsjs/core": "0.3.0"
   },
   "peerDependencies": {
     "tailwind-merge": "^2.5.0 || ^3.0.0",