@prongsjs/ui 0.0.0-stage → 0.2.0

package/dist/tooling/components.js

@@ -0,0 +1,156 @@
+const UNSAFE = {
+    name: 'unsafeClassName',
+    type: 'string',
+    description: 'Bypasses the intent. Needs a `// prongs-unsafe: <reason>` comment on the line above, and `prongs check` counts it.',
+};
+const VARS = {
+    name: 'vars',
+    type: 'Record<`--${string}`, string | number>',
+    description: "Values that come from data, as CSS variables the intent reads: `vars={{ '--accent': user.color }}`.",
+};
+/** Where an element sits, never how it looks. Spacing between elements comes from the parent <Layout>. */
+export const LAYOUT_PROPS = [
+    { name: 'align', type: "'start' | 'center' | 'end'", description: 'On text, the text alignment. On anything else, pushes it to that end of its row or column.' },
+    { name: 'width', type: "'auto' | 'full' | 'prose' | 'sm' | 'md' | 'lg'", description: 'Full width, or a maximum width.' },
+    { name: 'hideBelow', type: "'sm' | 'md' | 'lg'", description: 'Hidden on screens narrower than this breakpoint.' },
+    { name: 'showBelow', type: "'sm' | 'md' | 'lg'", description: 'Shown only on screens narrower than this breakpoint.' },
+    { name: 'truncate', type: 'boolean', description: 'One line, cut off with an ellipsis.' },
+    { name: 'nowrap', type: 'boolean', description: 'Keeps the text on one line.' },
+];
+export const COMPONENT_DOCS = {
+    Text: {
+        summary: 'Headings, running text and feedback messages. The intent decides the element (`<h1>`, `<p>`, `<span>`, `<pre>`) and the look.',
+        layoutProps: true,
+        props: [
+            { 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'",
+                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.' },
+            VARS,
+            UNSAFE,
+        ],
+        rules: [
+            'No `className` or `style`. If text needs to look different, it is a different intent.',
+            'Use `as` only to fix document structure, never to change the look.',
+            'Emphasis inside a sentence is plain `<strong>` or `<em>`, not another `<Text>`.',
+        ],
+    },
+    Action: {
+        summary: 'Everything the user presses: commands, links, navigation and choices. With `href` it renders a link, without one a `<button>`.',
+        layoutProps: true,
+        props: [
+            { name: 'intent', type: 'ActionIntent', description: 'What pressing it does: `action.*`, `nav.*` or `choice.*`.', required: true },
+            { name: 'href', type: 'string', description: 'Makes it a link (through the `LinkComponent` in `config.ts`, e.g. `next/link`).' },
+            { name: 'pressed', type: 'boolean', description: 'On or off, for toggles, choices and views. Sets `aria-pressed`; the intent styles it.' },
+            { name: 'current', type: 'boolean', description: 'Marks the page or step you are on. Sets `aria-current`; the intent styles it.' },
+            { name: 'icon', type: 'ReactNode', description: 'An icon shown before the text, or alone.' },
+            { 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`).' },
+            VARS,
+            UNSAFE,
+        ],
+        rules: [
+            'Name it for what it does (`action.delete`), not how it looks. `prongs check` warns when its label or handler says something else.',
+            'State goes in `pressed` or `current`, never in a different intent or extra classes.',
+            'An icon alone needs `label`.',
+            'No `className` or `style`.',
+        ],
+    },
+    Field: {
+        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: '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: 'children', type: 'ReactNode', description: 'For select fields: the `<option>`s.' },
+            { name: 'ref', type: 'Ref<HTMLInputElement>', description: 'Reaches the underlying element.' },
+            UNSAFE,
+        ],
+        rules: [
+            'Do not pass `type`: the intent sets it.',
+            'Label it with `label` (plus `hint` and `error`), which renders and wires the whole field; or give it an `aria-label` when the label is visible elsewhere, like a search box.',
+            'It takes the usual input attributes: `value`, `onChange`, `name`, `placeholder`, `required`...',
+        ],
+    },
+    Layout: {
+        summary: 'Page regions and groups. The intent decides the element (`<main>`, `<section>`, `<form>`, `<ul>`, `<li>`) and the arrangement.',
+        layoutProps: false,
+        props: [
+            { name: 'intent', type: 'LayoutIntent', description: 'What this region is: `layout.page`, `layout.form`, `layout.list`...', required: true },
+            {
+                name: 'className',
+                type: 'string',
+                description: 'Layout and spacing only: margins, sizes, flex and grid, gaps, padding, text alignment. Visual classes warn in development and fail `prongs check`.',
+            },
+            { name: 'hideBelow', type: "'sm' | 'md' | 'lg'", description: 'Hidden on screens narrower than this breakpoint: the desktop half of a region built twice.' },
+            { name: 'showBelow', type: "'sm' | 'md' | 'lg'", description: 'Shown only on screens narrower than this breakpoint: the phone half.' },
+            { name: 'align', type: "'start' | 'center' | 'end'", description: 'Pushes the region to that end of its row or column, like a group of controls at the end of a header.' },
+            { name: 'ref', type: 'Ref<HTMLElement>', description: 'Reaches the rendered element.' },
+            UNSAFE,
+        ],
+        rules: [
+            'The only component with a `className`, and only for layout.',
+            'Hide or show by screen size with `hideBelow` and `showBelow`, and push a region to one end with `align`, rather than classes.',
+            'A box that needs its own background or border is a different intent (`layout.panel`, `layout.notice`), not a class.',
+            'Pass `onSubmit` to a `layout.form`.',
+        ],
+    },
+    Media: {
+        summary: 'Images that identify a person or illustrate content, and frames that show another page (`media.embed`). Without a source it shows text instead, like initials.',
+        layoutProps: true,
+        props: [
+            { name: 'intent', type: 'MediaIntent', description: '`media.person` or `media.image`.', required: true },
+            { name: 'alt', type: 'string', description: 'What the image shows (for a frame, its title). Its accessible name, and the source of the default initials.', required: true },
+            { name: 'src', type: 'string | null', description: 'The image URL. When it is missing, the fallback shows.' },
+            { name: 'fallback', type: 'string', description: 'Text shown without an image. Defaults to the initials of `alt`.' },
+            { name: 'size', type: "'xs' | 'sm' | 'md' | 'lg' | 'xl'", description: 'For people: the size of the circle.' },
+            { name: 'loading', type: "'lazy' | 'eager'", description: 'When the image loads. Lazy by default.' },
+            { name: 'onError', type: '() => void', description: 'Called when the image fails, e.g. to clear `src` and show the fallback.' },
+            VARS,
+            UNSAFE,
+        ],
+        rules: ['`alt` is required.', 'No `className` or `style`.'],
+    },
+    Dialog: {
+        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: '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 },
+            { name: 'children', type: 'ReactNode', description: 'The content. It renders only while the dialog is open.', required: true },
+            UNSAFE,
+        ],
+        rules: ['Put a heading, the content and a `layout.actions` row inside.', 'Keep `open` in state and set it to false in `onClose`.'],
+    },
+    Popover: {
+        summary: 'Things that open next to the button that opened them, without blocking the page: menus, pickers, extra detail. Built on the native `popover` attribute, so a click outside or Escape closes it.',
+        layoutProps: false,
+        props: [
+            { name: 'intent', type: 'PopoverIntent', description: '`popover.menu`, `popover.picker` or `popover.info`.', required: true },
+            { name: 'trigger', type: 'ReactElement', description: 'The `<Action>` that opens it. Popover connects the two and places itself next to it.', required: true },
+            { 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: 'keepOpen', type: 'boolean', description: 'Stay open when something inside is pressed. Pickers that pick many stay open anyway.' },
+            UNSAFE,
+        ],
+        rules: [
+            'The trigger is an `<Action>` with a button, never a link. A picker’s trigger is `choice.open`, with `selectionSummary(options, value, placeholder)` as its text.',
+            'Whether a picker picks one or many comes from its intent, never a prop.',
+            'The arrow keys, Home, End and first letters move between items; Escape or a press closes it and focus goes back to the trigger.',
+            'Inside a menu, actions look like menu items whatever their intent; the menu decides.',
+            'Anything that needs the user’s full attention is a `<Dialog>`, not a popover.',
+        ],
+    },
+};

package/dist/tooling/index.d.ts

@@ -0,0 +1,17 @@
+import type { ProfileTooling } from '@prongsjs/core/engine';
+export type UiToolingOptions = {
+    /** Where the Prongs components live, relative to the project root. */
+    componentsDir: string;
+    /** How to run the CLI in this project, used in suggested commands. */
+    cli?: string;
+    /** The registry module, relative to the project root. Its classes are checked for raw values and unknown tokens. */
+    registryPath?: string;
+    /**
+     * Every CSS variable the project declares (in its CSS, or as `'--name'` keys it passes through
+     * `vars` and `style`). When given, the registry may only reference these.
+     */
+    tokens?: ReadonlySet<string>;
+};
+export declare function createUiTooling(options: UiToolingOptions): ProfileTooling;
+export { UI_RULE_DOCS, specExamples, uiSpecTooling } from './spec.js';
+export { themeCss, THEME_TOKENS, THEME_VARIABLES, SURFACE_TOKENS, SURFACE_CLASSES } from './theme.js';