@jasonsdevspace/design-kit 0.1.0-next.1 → 0.1.0-next.3

package/dist/react.d.ts

@@ -0,0 +1,137 @@
+import { type ComponentPropsWithRef, type ReactNode } from 'react';
+/** Where the portfolio is, and the section of it that lists the work. */
+export declare const PORTFOLIO_URL = "https://jasonsdevspace.com/";
+export declare const PORTFOLIO_WORK_URL = "https://jasonsdevspace.com/#work";
+/** Where the rest of the work is. */
+export declare const GITHUB_PROFILE_URL = "https://github.com/jasonsdevspace";
+/**
+ * The first stop for the keyboard, out of sight until it takes focus, and then at the column's
+ * inset. Following it moves focus past the strip to the element whose id it names, the page's main
+ * content, which has a tabindex of -1 so it can take focus.
+ */
+export declare const SkipLink: ({ target, children, }: {
+    /** The id of the element the link leads to. */
+    readonly target?: string;
+    readonly children?: ReactNode;
+}) => import("react").JSX.Element;
+/** A page of the demo's that the chrome links to, and can mark as the one it sits on. */
+type ChromePage = 'about';
+/**
+ * Whose demo this is, above the page, with three links together on the left. It is a navigation
+ * landmark in a plain div rather than a header, so the demo's own header stays the page's one
+ * banner. A demo with switches of its own puts them beside the links, in a landmark of their own
+ * named for them, and while they are on their way the strip keeps their room in that section,
+ * unnamed and so no landmark.
+ */
+export declare const PortfolioStrip: ({ about, source, current, tools, toolsLabel, toolsWaiting, }: {
+    /** The demo's explainer, relative to the page or absolute. */
+    readonly about: string;
+    /** The demo's repository. */
+    readonly source: string;
+    /** The link that is the page the strip sits on, marked as the current page. */
+    readonly current?: ChromePage;
+    /** The demo's own switches, drawn beside the links. */
+    readonly tools?: ReactNode;
+    /** The name a screen reader gives the switches' landmark. */
+    readonly toolsLabel?: string;
+    /**
+     * The switches are on their way, so the strip keeps the room of one row of the kit's controls
+     * in their section, empty and unnamed, so no landmark, until `tools` holds them and the section
+     * takes its name.
+     */
+    readonly toolsWaiting?: boolean;
+}) => import("react").JSX.Element;
+/**
+ * The exit after a long scroll: whose project this is, how it works, where the source and the rest
+ * of the work are, and the license, with anything the demo adds of its own after them.
+ */
+export declare const DemoFooter: ({ name, about, source, current, license, licenseName, children, }: {
+    /** The demo's name, as the footer's sentence opens with it. */
+    readonly name: string;
+    /** The demo's explainer, relative to the page or absolute. */
+    readonly about: string;
+    /** The demo's repository. */
+    readonly source: string;
+    /** The link that is the page the footer sits on, marked as the current page. */
+    readonly current?: ChromePage;
+    /** The demo's license, the LICENSE file on the repository's main branch unless given. */
+    readonly license?: string;
+    /** What the license is called, as the footer's sentence names it. */
+    readonly licenseName?: string;
+    /** What the demo adds after the license, as sentences of its own. */
+    readonly children?: ReactNode;
+}) => import("react").JSX.Element;
+type NativeButton = Omit<ComponentPropsWithRef<'button'>, 'style' | 'disabled' | 'aria-disabled' | 'aria-pressed'>;
+/**
+ * A button's own props: the accent for the one action a view leads with, `pressed` for a toggle
+ * that stands alone, and `off`, beside a `<button>`'s own, its `ref` among them, which holds the
+ * button drawn for a page that moves focus to it. The accent is never a toggle, so the two do not
+ * go together.
+ */
+export type ButtonProps = NativeButton & {
+    /** Off, but still in the tab order, so a keyboard keeps its place and finds out why. */
+    readonly off?: boolean;
+} & ({
+    readonly accent: true;
+    readonly pressed?: never;
+} | {
+    readonly accent?: false;
+    /** Whether the toggle is on. False still marks it a toggle, undefined an action. */
+    readonly pressed?: boolean;
+});
+/**
+ * A button, of type button unless a page gives another, so it never submits a form by surprise.
+ * Off, it is marked aria-disabled rather than disabled, since a disabled button that has focus
+ * drops it, and a press of it runs no click handler of the page's and stops the form it would
+ * submit. The page's other handlers, for keys or a pointer, still run, and check `off` themselves.
+ */
+export declare const Button: ({ accent, pressed, off, type, className, onClick, children, ...native }: ButtonProps) => import("react").JSX.Element;
+/** What a field draws around its control. */
+type FieldParts = {
+    /** The label, which names the control and focuses it when pressed. */
+    readonly label: ReactNode;
+    /** What helps a visitor fill the field, read as its description. */
+    readonly hint?: ReactNode;
+    /** What is wrong with the value, drawn only when given, which marks the control invalid. */
+    readonly error?: ReactNode;
+    /** The control's id, made with useId unless a page gives one, as it does for a link to it. */
+    readonly id?: string;
+};
+export type InputFieldProps = FieldParts & Omit<ComponentPropsWithRef<'input'>, 'style' | 'id' | 'aria-invalid' | 'children'>;
+/**
+ * A text input with its label, hint and error, the input taking every other prop given, its `ref`
+ * among them, which holds the input drawn for a page that moves focus to it.
+ */
+export declare const InputField: (props: InputFieldProps) => import("react").JSX.Element;
+export type SelectFieldProps = FieldParts & Omit<ComponentPropsWithRef<'select'>, 'style' | 'id' | 'aria-invalid'>;
+/**
+ * A native select with its label, hint and error, its children the options, and the select taking
+ * every other prop given, its `ref` among them, which holds the select drawn for a page that moves
+ * focus to it.
+ */
+export declare const SelectField: (props: SelectFieldProps) => import("react").JSX.Element;
+/** What a callout is about: news, something that went right, or something that went wrong. */
+export type CalloutTone = 'info' | 'success' | 'danger';
+/**
+ * A message set apart from the page, with an optional title before it and actions after it. It has
+ * no role unless the page gives `live`, whatever its tone, since a message on the page when it
+ * loads is read in its place. A live message is drawn even when empty, so the page can mount it
+ * first and fill it after, which is when a screen reader reads it. The role sits on the message,
+ * which holds the title and the tone's word too, so they are read with it, and the actions are
+ * not.
+ */
+export declare const Callout: ({ tone, title, headingLevel, live, prefix, actions, children, }: {
+    readonly tone?: CalloutTone;
+    /** What the callout is about, drawn before its message. */
+    readonly title?: ReactNode;
+    /** The title's heading level, where the callout is a section a visitor would jump to. */
+    readonly headingLevel?: 2 | 3 | 4 | 5 | 6;
+    /** A message a screen reader reads when it changes, politely or at once. */
+    readonly live?: "status" | "alert";
+    /** The word read before the title or the message, the tone's own unless given. */
+    readonly prefix?: string;
+    /** Buttons or links that act on the message. */
+    readonly actions?: ReactNode;
+    readonly children?: ReactNode;
+}) => import("react").JSX.Element;
+export {};

package/dist/react.js

@@ -0,0 +1,130 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useId } from 'react';
+/*
+ * The page chrome a demo draws around its page, a skip link, a strip above the page that says
+ * whose demo it is and a footer below it, and the buttons, fields and callouts on the page itself.
+ * Each component draws the markup components.css styles and nothing else, with no stylesheet of
+ * its own and no style attribute, so a page without React writes the same markup by hand, and a
+ * page whose policy allows styles only from its own origin draws it. A control's state is a
+ * native or ARIA attribute, never a class of the kit's.
+ */
+/** Whether a slot holds something to draw: a demo's `cond && <X />` leaves false or null. */
+const drawn = (node) => node !== undefined && node !== null && node !== false;
+/** Where the portfolio is, and the section of it that lists the work. */
+export const PORTFOLIO_URL = 'https://jasonsdevspace.com/';
+export const PORTFOLIO_WORK_URL = 'https://jasonsdevspace.com/#work';
+/** Where the rest of the work is. */
+export const GITHUB_PROFILE_URL = 'https://github.com/jasonsdevspace';
+/**
+ * The first stop for the keyboard, out of sight until it takes focus, and then at the column's
+ * inset. Following it moves focus past the strip to the element whose id it names, the page's main
+ * content, which has a tabindex of -1 so it can take focus.
+ */
+export const SkipLink = ({ target = 'main-content', children = 'Skip to content', }) => (_jsx("a", { className: "dk-skip", href: `#${target}`, children: children }));
+/** The mark a link to `page` takes when it is the page the chrome sits on, and none otherwise. */
+const currentAs = (current, page) => current === page ? 'page' : undefined;
+/**
+ * Whose demo this is, above the page, with three links together on the left. It is a navigation
+ * landmark in a plain div rather than a header, so the demo's own header stays the page's one
+ * banner. A demo with switches of its own puts them beside the links, in a landmark of their own
+ * named for them, and while they are on their way the strip keeps their room in that section,
+ * unnamed and so no landmark.
+ */
+export const PortfolioStrip = ({ about, source, current, tools, toolsLabel = 'Demo', toolsWaiting = false, }) => (_jsxs("div", { className: "dk-strip", children: [_jsxs("nav", { className: "dk-strip-links", "aria-label": "Portfolio", children: [_jsx("a", { href: PORTFOLIO_WORK_URL, children: "A demo by Jason Poteet" }), _jsx("a", { href: about, "aria-current": currentAs(current, 'about'), children: "How it works" }), _jsx("a", { href: source, children: "Source on GitHub" })] }), drawn(tools) ? (_jsx("section", { className: "dk-strip-tools", "aria-label": toolsLabel, children: tools })) : toolsWaiting ? (_jsx("section", { className: "dk-strip-tools", children: _jsx("span", { className: "dk-strip-room" }) })) : null] }));
+/**
+ * The exit after a long scroll: whose project this is, how it works, where the source and the rest
+ * of the work are, and the license, with anything the demo adds of its own after them.
+ */
+export const DemoFooter = ({ name, about, source, current, license = `${source.endsWith('/') ? source.slice(0, -1) : source}/blob/main/LICENSE`, licenseName = 'MIT license', children, }) => (_jsx("footer", { className: "dk-footer", children: _jsxs("p", { children: [name, " is a portfolio project by ", _jsx("a", { href: PORTFOLIO_URL, children: "Jason Poteet" }), ".", ' ', _jsx("a", { href: about, "aria-current": currentAs(current, 'about'), children: "How it works" }), ", in plain words. The ", _jsx("a", { href: source, children: "source" }), " and", ' ', _jsx("a", { href: GITHUB_PROFILE_URL, children: "more work" }), " are on GitHub, under the", ' ', _jsx("a", { href: license, children: licenseName }), ".", drawn(children) ? _jsxs(_Fragment, { children: [" ", children] }) : null] }) }));
+/** Whether a slot holds words to draw, an empty string being none. */
+const filled = (node) => drawn(node) && node !== '';
+/**
+ * A list of names an attribute holds, such as the classes a component draws, its own first and a
+ * page's after them, or the ids that describe a control, with any left out or empty dropped.
+ */
+const spaced = (...names) => names.filter((name) => typeof name === 'string' && name !== '').join(' ');
+/**
+ * A button, of type button unless a page gives another, so it never submits a form by surprise.
+ * Off, it is marked aria-disabled rather than disabled, since a disabled button that has focus
+ * drops it, and a press of it runs no click handler of the page's and stops the form it would
+ * submit. The page's other handlers, for keys or a pointer, still run, and check `off` themselves.
+ */
+export const Button = ({ accent, pressed, off = false, type = 'button', className, onClick, children, ...native }) => (_jsx("button", { ...native, type: type, className: spaced('dk-button', accent === true && 'dk-button-accent', className), "aria-pressed": pressed, "aria-disabled": off ? true : undefined, onClick: off
+        ? (event) => {
+            event.preventDefault();
+        }
+        : onClick, children: children }));
+/**
+ * The attributes that tie a control to its label, hint and error. Only what is drawn is listed,
+ * the hint before the error as they are read, then any description the page gives of its own.
+ */
+const useField = ({ id, hint, error }, own) => {
+    const made = useId();
+    // An empty id would tie nothing, so it is made as one left out is.
+    const control = id === undefined || id === '' ? made : id;
+    const hinted = filled(hint);
+    const wrong = filled(error);
+    const describedBy = spaced(hinted && `${control}-hint`, wrong && `${control}-error`, own);
+    return {
+        id: control,
+        hint: hinted,
+        error: wrong,
+        wired: {
+            id: control,
+            'aria-describedby': describedBy === '' ? undefined : describedBy,
+            'aria-invalid': wrong ? true : undefined,
+        },
+    };
+};
+/**
+ * A field's label, hint and error around its control. The error sits above the control, so a
+ * phone's keyboard never covers it, and starts with a word a screen reader reads, so the error is
+ * told from the hint by more than its color. It is not live, since a form that fails in several
+ * fields at once would speak over itself, so the page says when an error appears.
+ */
+const Field = ({ parts, field, children, }) => (_jsxs("div", { className: "dk-field", children: [_jsx("label", { className: "dk-field-label", htmlFor: field.id, children: parts.label }), field.hint ? (_jsx("p", { className: "dk-field-hint", id: `${field.id}-hint`, children: parts.hint })) : null, field.error ? (_jsxs("p", { className: "dk-field-error", id: `${field.id}-error`, children: [_jsx("span", { className: "dk-visually-hidden", children: "Error: " }), parts.error] })) : null, children] }));
+/**
+ * A text input with its label, hint and error, the input taking every other prop given, its `ref`
+ * among them, which holds the input drawn for a page that moves focus to it.
+ */
+export const InputField = (props) => {
+    const { label: _label, hint: _hint, error: _error, id: _id, className, ...rest } = props;
+    const { 'aria-describedby': own, ...native } = rest;
+    const field = useField(props, own);
+    return (_jsx(Field, { parts: props, field: field, children: _jsx("input", { className: spaced('dk-input', className), ...native, ...field.wired }) }));
+};
+/**
+ * A native select with its label, hint and error, its children the options, and the select taking
+ * every other prop given, its `ref` among them, which holds the select drawn for a page that moves
+ * focus to it.
+ */
+export const SelectField = (props) => {
+    const { label: _label, hint: _hint, error: _error, id: _id, className, ...rest } = props;
+    const { 'aria-describedby': own, children, ...native } = rest;
+    const field = useField(props, own);
+    return (_jsx(Field, { parts: props, field: field, children: _jsx("select", { className: spaced('dk-select', className), ...native, ...field.wired, children: children }) }));
+};
+/** The word a screen reader reads before each tone's message, so the tone is not color alone. */
+const TONE_WORDS = {
+    info: '',
+    success: 'Success: ',
+    danger: 'Error: ',
+};
+/** The element a callout's title is drawn as, at each heading level a page may give it. */
+const HEADINGS = { 2: 'h2', 3: 'h3', 4: 'h4', 5: 'h5', 6: 'h6' };
+/**
+ * A message set apart from the page, with an optional title before it and actions after it. It has
+ * no role unless the page gives `live`, whatever its tone, since a message on the page when it
+ * loads is read in its place. A live message is drawn even when empty, so the page can mount it
+ * first and fill it after, which is when a screen reader reads it. The role sits on the message,
+ * which holds the title and the tone's word too, so they are read with it, and the actions are
+ * not.
+ */
+export const Callout = ({ tone = 'info', title, headingLevel, live, prefix = TONE_WORDS[tone], actions, children, }) => {
+    // A level the types refuse, as a page in plain JavaScript can pass, draws a paragraph.
+    const Title = (headingLevel === undefined ? undefined : HEADINGS[headingLevel]) ?? 'p';
+    const titled = filled(title);
+    const said = filled(children);
+    const word = prefix === '' ? null : _jsx("span", { className: "dk-visually-hidden", children: prefix });
+    return (_jsxs("div", { className: spaced('dk-callout', tone !== 'info' && `dk-callout-${tone}`), children: [titled || said || live !== undefined ? (_jsxs("div", { className: "dk-callout-body", role: live, children: [titled ? (_jsxs(Title, { className: "dk-callout-title", children: [word, title] })) : null, !titled && said ? word : null, said ? children : null] })) : null, filled(actions) ? _jsx("div", { className: "dk-callout-actions", children: actions }) : null] }));
+};

package/dist/tokens.css

@@ -1,26 +1,27 @@
 /*
  * The kit's named values: the scale a page's styles are drawn from, and the color roles a demo
- * fills with its own palette. Every name carries the dk prefix, so a page that loads the kit
- * beside its own styles keeps its own names.
+ * fills with its own palette. Every name carries the dk prefix, so a page that loads the kit beside
+ * its own styles keeps its own names.
  *
- * Each color role holds its light and its dark value in one light-dark(), which picks by the
- * color scheme of the element it is drawn on. The scheme follows data-theme on the root when a
- * page sets it, as the portfolio does with the theme a visitor saved, and the system's otherwise.
- * A demo with its own palette sets the roles again on its root, both values at once.
+ * Each color role holds its light and its dark value in one light-dark(), which picks by the color
+ * scheme of the element it is drawn on. The scheme follows data-theme on the root when a page sets
+ * it, as the portfolio does with the theme a visitor saved, and the system's otherwise. A demo with
+ * its own palette sets the roles again on its root, both values at once.
  *
  * Every rule in the kit sits in one of its layers, declared here in order, so a page's own rule
  * outside a layer wins over the kit's, the cut to motion in the base aside, and a page that names
  * dk among layers of its own sets where dk goes. A demo's own :root outside a layer wins the same
- * way, whichever sheet loads first. Across the kit, every selector but the visually hidden class is
- * one :where(), followed at most by a focus pseudo-class, and here each is a :where() alone, so
- * nothing in the tokens carries weight.
+ * way, whichever sheet loads first. Across the kit, every selector is one of the kit's own classes
+ * or one :where(), followed at most by a focus pseudo-class or, in the base alone, a
+ * pseudo-element, and here each is a :where() alone, so nothing in the tokens carries weight.
  *
  * Every text pairing the palette is meant for passes 4.5 to 1 in both themes, and a control's edge
  * 3 to 1 against what it sits on. The focus ring is in the accent, held at 4.5 to 1 as a link. A
  * test holds the palette to both.
  *
- * Which unit goes where: rem for anything that should grow with the visitor's own text size, and
- * px for what must not scale, a border, the focus ring and a shadow.
+ * Which unit goes where: rem for anything that should grow with the visitor's own text size, em for
+ * code set in running text, which sizes to the text around it, and px for what must not scale, a
+ * border, the focus ring and a shadow.
  */
 
 @layer dk.tokens, dk.base, dk.components;
@@ -43,7 +44,7 @@
 
         /* The lines between things, and the stronger edge of a field or button a visitor uses. */
         --dk-line: light-dark(#d9d9d9, #3a3a3a);
-        --dk-control: light-dark(#858585, #7a7a7a);
+        --dk-control: light-dark(#858585, #7d7d7d);
 
         /* Links, the focus ring and the one action a page leads with, and the text drawn on it. */
         --dk-accent: light-dark(#1f4fd8, #8fb0ff);
@@ -73,6 +74,8 @@
         --dk-text-title: 1.25rem;
         --dk-text-heading: 1.5rem;
         --dk-text-display: 1.75rem;
+        /* Code, a step under the text around it, since mono type looks larger at the same size. */
+        --dk-text-code: 0.9em;
         --dk-leading-tight: 1.2;
         --dk-leading-body: 1.5;
         --dk-weight-normal: 400;
@@ -98,8 +101,11 @@
         /* The height of the portfolio strip's row, and of each link in it. */
         --dk-strip: 2.5rem;
 
-        /* The width a page of reading holds to, and the widest a page's column grows. */
-        --dk-measure: 42rem;
+        /*
+         * The width a page of reading holds to, no more than 80 characters a line in the body size,
+         * and the widest a page's column grows.
+         */
+        --dk-measure: 34rem;
         --dk-column: 72rem;
 
         /* What floats over the page, and what dims the page behind it, darker on a dark page. */

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@jasonsdevspace/design-kit",
-    "version": "0.1.0-next.1",
-    "description": "Design tokens, base styles and the theme script for the demos on jasonsdevspace.com.",
+    "version": "0.1.0-next.3",
+    "description": "Design tokens, base styles, a theme script, page chrome, buttons, fields, callouts and an explainer layout for the demos on jasonsdevspace.com.",
     "keywords": [
         "design-tokens",
         "design-system",
@@ -10,7 +10,8 @@
         "dark-mode",
         "light-dark",
         "theme",
-        "vite-plugin"
+        "vite-plugin",
+        "react"
     ],
     "license": "MIT",
     "author": "Jason Poteet",
@@ -27,10 +28,15 @@
     "exports": {
         "./tokens.css": "./dist/tokens.css",
         "./base.css": "./dist/base.css",
+        "./components.css": "./dist/components.css",
         "./theme": {
             "types": "./dist/theme.d.ts",
             "default": "./dist/theme.js"
         },
+        "./react": {
+            "types": "./dist/react.d.ts",
+            "default": "./dist/react.js"
+        },
         "./vite": {
             "types": "./dist/vite.d.ts",
             "default": "./dist/vite.js"
@@ -55,9 +61,13 @@
         "prepack": "npm run build"
     },
     "peerDependencies": {
+        "react": "^19.3.0",
         "vite": ">=8"
     },
     "peerDependenciesMeta": {
+        "react": {
+            "optional": true
+        },
         "vite": {
             "optional": true
         }