@nanisoft/prism-ui 0.13.0 → 0.16.0

package/dist/blocks/project-list-01/project-list.js

@@ -0,0 +1,305 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useId } from 'react';
+import { Avatar, AvatarFallback, AvatarImage } from '../../components/ui/avatar.js';
+import { CtaLink } from '../../components/ui/cta-link.js';
+import { Progress } from '../../components/ui/progress.js';
+import { RelativeTime } from '../../components/ui/relative-time.js';
+import { Section, SectionHeading } from '../../components/ui/section.js';
+import { Status } from '../../components/ui/status.js';
+import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from '../../components/ui/table.js';
+import { Tag } from '../../components/ui/tag-group.js';
+import { cn } from '../../lib/utils.js';
+/**
+ * The tone a project's state is drawn in, from the semantic contract and no other.
+ *
+ * This Block takes the state as the caller's own string rather than as a closed
+ * union, and that is the one difference from `Project01` and it is deliberate: a
+ * project index holds projects drawn from more than one source in most products,
+ * and a tracker with its own state names will not match a five-value union. So
+ * there is no tone to derive from here, and the table below is the caller's to
+ * extend, which is a cost and not a convenience: a caller whose states are not
+ * the five below has to map them, and a caller whose states *are* those five gets
+ * the mapping for free by spelling the same words.
+ *
+ * The alternative, narrowing the state to the same five positions `Project01`
+ * uses, would have been a Block that decided what a project may be in, and a
+ * project index is exactly the surface where that decision does the most damage:
+ * a row that renders an unrecognised state as neutral is a row that looks
+ * deliberate and says nothing.
+ */
+const DEFAULT_TONE = {
+    planning: 'info',
+    active: 'success',
+    blocked: 'warning',
+    complete: 'success',
+    archived: 'neutral',
+};
+/**
+ * The tone a state is drawn in, falling back to the supporting ink.
+ *
+ * `neutral` for a state this table does not name, and the reason is that an
+ * unrecognised state is not an emergency: it is a vocabulary this Block has not
+ * been taught, and drawing it in the alarm colour would turn a naming mismatch
+ * into a page of red rows. The fallback is visible in the markup as the state
+ * value on the row, so a consumer reading their own page can see which states
+ * need mapping rather than guessing.
+ */
+function toneOf(state) {
+    return DEFAULT_TONE[state] ?? 'neutral';
+}
+/**
+ * The classes each cell takes, before the caller's own layout classes merge in.
+ *
+ * The two prose cells are told to wrap and the rest keep the default, because
+ * `table.tsx` sets every cell to `whitespace-nowrap` so a column of numbers lines
+ * up, and a summary and a set of chips are not numbers. A table that scrolls a
+ * sentence sideways to keep it on one line is a table nobody reads a whole row of.
+ */
+const CELL = {
+    name: 'font-medium whitespace-normal',
+    summary: 'text-muted-foreground whitespace-normal',
+    state: 'whitespace-nowrap',
+    owner: 'whitespace-nowrap',
+    progress: 'min-w-40',
+    updated: 'text-muted-foreground whitespace-nowrap text-sm',
+    tags: 'whitespace-normal',
+    href: 'text-right whitespace-nowrap',
+};
+/**
+ * The initials a name produces, and the rule that produces them.
+ *
+ * Two letters from the first and last words, and the first two characters of a
+ * single word. It is the same rule `AvatarGroup`, `Team01` and `Project01` apply
+ * and it is repeated here for the reason `Team01` states in full: that helper is
+ * private to its module and exporting it would make a private derivation part of
+ * the published surface of a Component in order to save six lines in a Block. The
+ * cost of the repetition is named rather than hidden, because four modules now
+ * carry this rule and a change to it is a change in four.
+ */
+function initialsOf(name) {
+    const words = name.trim().split(/\s+/).filter(Boolean);
+    const first = words[0];
+    if (first === undefined)
+        return '';
+    if (words.length === 1)
+        return first.slice(0, 2).toUpperCase();
+    return `${first.charAt(0)}${words[words.length - 1].charAt(0)}`.toUpperCase();
+}
+/**
+ * The cell one column draws for one project, in both forms of this Block.
+ *
+ * One function rather than one per variant, and that is what makes the two forms
+ * the same Block rather than two Blocks that happen to share a heading. The rows
+ * form draws every cell it has room for; the table form draws the ones the caller
+ * declared; and the cell itself is written once, so a caller's state words, their
+ * progress sentence and their moment reading are the same text in either form.
+ */
+function cellOf(id, project) {
+    switch (id) {
+        case 'name':
+            return project.name;
+        case 'summary':
+            return project.summary ?? null;
+        case 'state':
+            // The guard above the return has already refused a project with no words for
+            // its state, so the second half of this fallback cannot be reached. It is
+            // spelled rather than left to the type because `stateLabel` is optional in the
+            // type on purpose: a caller arriving from JavaScript should get the diagnostic
+            // from the guard, which names the project, rather than a bare machine value
+            // drawn where the words belong.
+            return _jsx(Status, { size: "sm", tone: toneOf(project.state), label: project.stateLabel ?? project.state });
+        case 'owner':
+            if (project.owner === undefined)
+                return null;
+            return (_jsxs("span", { "data-slot": "project-list-owner", className: "flex min-w-0 items-center gap-2", children: [project.owner.avatar === undefined ? null : (_jsxs(Avatar, { className: "size-6", children: [project.owner.avatar.src === undefined ? null : (_jsx(AvatarImage, { src: project.owner.avatar.src, alt: "" })), _jsx(AvatarFallback, { className: "text-mono", children: initialsOf(project.owner.avatar.name) })] })), _jsx("span", { className: "truncate text-sm", children: project.owner.name })] }));
+        case 'progress':
+            if (project.progress === undefined)
+                return null;
+            return (_jsx(Progress, { value: project.progress, valueText: project.progressLabel?.(project.progress, project.name) }));
+        case 'updated':
+            if (project.updated === undefined)
+                return null;
+            return _jsx(RelativeTime, { date: project.updated, relative: project.updatedLabel?.(project.updated) });
+        case 'tags':
+            if (project.tags === undefined)
+                return null;
+            return (_jsx("span", { "data-slot": "project-list-tags", className: "flex flex-wrap items-center gap-1.5", children: project.tags.map((tag) => (_jsx(Tag, { label: tag.label }, tag.id))) }));
+        case 'href':
+            if (project.href === undefined || project.hrefLabel === undefined)
+                return null;
+            return (_jsx(CtaLink, { href: project.href, size: "sm", variant: "ghost", children: project.hrefLabel }));
+    }
+}
+/**
+ * Whether any project in the set carries the fact a column draws.
+ *
+ * A declared column no project fills is a column of empty cells, and a column of
+ * empty cells is a column every reader scans twice before deciding it is nothing.
+ * It is invisible in review, because the header row looks finished and the body
+ * rows look uniform, and it is the reason the run throws rather than rendering the
+ * gap: a caller who declared a column meant to see something in it.
+ *
+ * A switch over the field rather than a call to `cellOf` and a null check, because
+ * the question here is what the data holds and the other function's question is
+ * what to draw, and asking one to answer the other builds a React element per
+ * project per column to throw it away.
+ */
+function carries(id, projects) {
+    switch (id) {
+        case 'name':
+        case 'state':
+            // Both are on every project, so a list with a row in it always has them.
+            return projects.length > 0;
+        case 'summary':
+            return projects.some((project) => project.summary !== undefined);
+        case 'owner':
+            return projects.some((project) => project.owner !== undefined);
+        case 'progress':
+            return projects.some((project) => project.progress !== undefined);
+        case 'updated':
+            return projects.some((project) => project.updated !== undefined);
+        case 'tags':
+            return projects.some((project) => project.tags !== undefined);
+        case 'href':
+            return projects.some((project) => project.href !== undefined);
+    }
+}
+/**
+ * A list of projects, as rows or as a real table, with a toolbar, a filter column
+ * and an empty state the caller writes.
+ *
+ * **This is the many-projects counterpart to `Project01`, and the two take the
+ * same field names on purpose.** A consumer with a project model has one model: a
+ * caller maps their project onto `name`, `state`, `owner`, `progress`, `updated`
+ * and `tags` once, and that mapping feeds a detail header and a list row without
+ * either Block knowing the other exists. The alternative, a list Block with its own
+ * field names, gives every consumer two models to keep in step, and the two drift
+ * within a release rather than across one, which is the failure mode this
+ * repository is organised against. The cost is stated rather than hidden: a row has
+ * nowhere to put a stage list, a span of dates and an action slot, so those fields
+ * are absent from the row type instead of being quietly ignored.
+ *
+ * **The two variants answer different questions, and `rows` is the one that is
+ * scanned while `table` is the one that is compared.** A short list where the
+ * summary is the point wants the rows form: each row is one project read top to
+ * bottom, its name and its sentence and its state, with no header row to announce
+ * and no columns to align, and the reader's job is to find the one they want. A
+ * long list wants the table form, and the moment that changes is the moment a
+ * reader starts comparing a value in one row against the same value in another:
+ * that is when the content is records with columns rather than a list of things,
+ * which is the exact boundary `ListPanel` draws in its own documentation. The
+ * three things a `<div>` grid gets wrong are the three a reader of forty projects
+ * needs: there is no `th` to navigate by, so a screen reader announces a bare run
+ * of values with no idea which is the state and which is the owner; there is no
+ * row header, so a reader who lands on one cell is not told which project they are
+ * in; and there is nothing for a browser's own table commands to act on.
+ *
+ * **The filter column is a slot, and it is a slot rather than a set of named
+ * controls because a projects index is not always faceted.** `FilterPanel` is the
+ * Component it is for, and the panel is a column, so the slot is drawn in a narrow
+ * aside at the leading edge with the list beside it. A caller whose filters are a
+ * popover trigger or a row of chips passes them in `toolbar` instead, and a Block
+ * that drew its own filters would be deciding that every projects index is a
+ * faceted browser, which most of them are not.
+ *
+ * **The order is the caller's and this Block does not sort.** The same argument
+ * `ResourceList01` gives and the same one `Leaderboard01` gives harder: a projects
+ * index is very often already ordered by a query that knows which project is live,
+ * and a Block that sorted by name or by date would undo a decision it cannot see.
+ * A `sort` prop would be a second derivation the caller then has to keep in step
+ * with their own data, and two orderings of one list that disagree is a list whose
+ * order nobody can fix without changing code in two places.
+ *
+ * **The run fails on five ways a projects table can be wrong, and every one of
+ * them reaches a developer rather than a reader.** A `columns` array with no
+ * `name` in it is a header row with a cell fewer than every body row and a table
+ * whose rows have no identity. A `columns` array that names the same cell twice is
+ * a table with two columns reading the same value. A column no project carries is
+ * a column of empty cells. A project with a state and no words for it is a dot
+ * with nothing beside it. And a project with a progress and no sentence for it, or
+ * a moment and no sentence for it, or a link and no words on it, is a figure
+ * announcing a bare number, a date with no claim about how old it is, and a link
+ * announced by its address. Each message names the project rather than the index,
+ * because a caller with forty projects needs to know which one.
+ *
+ * It is a server Component: no hook, no state, no client code of its own and no
+ * router. The only client code it can pull in is one `Progress` island per project
+ * that asks for a fill, and the portrait is `Avatar`, whose only client work is
+ * measuring whether an image has loaded.
+ */
+export function ProjectList01({ eyebrow, title, description, projects, toolbar, filters, footer, empty, variant = 'rows', columns, headingLevel = 'h2', className, }) {
+    // The handle a table below takes its name from; see the note on the table.
+    const headingId = useId();
+    // Checked before anything is drawn, so the run fails once with the name of the
+    // project rather than once per row with a malformed cell on the page.
+    for (const project of projects) {
+        if (!project.stateLabel) {
+            throw new Error(`ProjectList01: the project "${project.name}" carries a state and no stateLabel, so its cell ` +
+                'would be a dot with no sentence beside it, which is the one thing a reader who cannot see the ' +
+                `tone learns nothing from. Pass the words your readers use for that state.`);
+        }
+        if (project.progress !== undefined && !project.progressLabel) {
+            throw new Error(`ProjectList01: the project "${project.name}" carries a progress and no progressLabel, so the ` +
+                'bar would announce a bare number meaning whatever the reader assumes it is a percentage of. ' +
+                `Pass the words for the value, or drop the progress.`);
+        }
+        if (project.updated !== undefined && !project.updatedLabel) {
+            throw new Error(`ProjectList01: the project "${project.name}" carries a moment and no updatedLabel, so the ` +
+                'cell would be a date with nothing beside it and no claim about how old it is. Pass the ' +
+                `sentence, or drop the moment.`);
+        }
+        if (project.href !== undefined && !project.hrefLabel) {
+            throw new Error(`ProjectList01: the project "${project.name}" carries an href with no hrefLabel, so the link ` +
+                'would be announced by its address, which is punctuation rather than a name. Pass the words ' +
+                `that say where it goes, or drop the href.`);
+        }
+    }
+    const heading = (_jsx(SectionHeading, { as: headingLevel, id: headingId, align: "left", eyebrow: eyebrow, title: title, description: description }));
+    /*
+     * The empty state, and it is drawn before the column checks rather than after.
+     *
+     * A caller whose filter matched nothing has a set of projects of length zero
+     * and a set of columns they declared for the list that is not there, and the
+     * two checks below would both refuse: a table with no `name` column, and eight
+     * columns no project carries. Both refusals are right about a table with rows
+     * and wrong about a table that is showing the caller's own sentence about there
+     * being no rows, so the empty state is settled first.
+     */
+    if (projects.length === 0) {
+        return (_jsx(Section, { "data-slot": "project-list-01", "data-variant": variant, "data-empty": "true", className: cn(className), children: _jsxs("div", { className: "flex flex-col gap-8", children: [heading, _jsx("div", { "data-slot": "project-list-empty", className: "text-muted-foreground text-pretty text-sm", children: empty })] }) }));
+    }
+    if (variant === 'table') {
+        const declared = columns ?? [];
+        const seen = new Set();
+        for (const column of declared) {
+            if (seen.has(column.id)) {
+                throw new Error(`ProjectList01: the column "${column.id}" is declared twice, so the table would have two ` +
+                    'columns reading the same value and every cell after the first would be read under the ' +
+                    `wrong name. Declare each cell once.`);
+            }
+            if (!carries(column.id, projects)) {
+                throw new Error(`ProjectList01: the "${column.id}" column was declared and no project in this list carries ` +
+                    'it, so the table would have a column of empty cells, which is a column every reader scans ' +
+                    `twice. Pass the field, or drop the column.`);
+            }
+            seen.add(column.id);
+        }
+        if (!seen.has('name')) {
+            throw new Error('ProjectList01: the columns name no "name" cell, so the header row would have a cell fewer ' +
+                'than every body row and a reader who lands on one cell would not be told which project they ' +
+                'are in. Declare the name column, which is also the row header for every row.');
+        }
+    }
+    const list = variant === 'table' ? (_jsx("div", { "data-slot": "project-list", "data-variant": variant, children: _jsx("div", { className: "border-border overflow-hidden rounded-xl border", children: _jsxs(Table, { "aria-labelledby": headingId, children: [_jsx(TableHeader, { children: _jsx(TableRow, { children: (columns ?? []).map((column) => (_jsx(TableHead, { scope: "col", className: column.className, children: column.header }, column.id))) }) }), _jsx(TableBody, { children: projects.map((project) => (_jsx(TableRow, { "data-slot": "project-list-row", "data-project": project.id, children: (columns ?? []).map((column) => 
+                            // The name is a row header, so a reader who navigates into a
+                            // single cell is told which project they are looking at rather
+                            // than hearing a value with nothing to attach it to.
+                            column.id === 'name' ? (_jsx(TableHead, { scope: "row", className: cn(CELL[column.id], column.className), children: cellOf(column.id, project) }, column.id)) : (_jsx(TableCell, { className: cn(CELL[column.id], column.className), children: cellOf(column.id, project) }, column.id))) }, project.id))) })] }) }) })) : (_jsx("ul", { "data-slot": "project-list", "data-variant": variant, className: "flex flex-col", children: projects.map((project) => (_jsxs("li", { "data-slot": "project-list-row", "data-project": project.id, "data-state": project.state, className: "border-border flex flex-wrap items-start justify-between gap-x-8 gap-y-4 border-b py-5 first:border-t", children: [_jsxs("div", { className: "flex min-w-0 flex-1 flex-col gap-2", children: [_jsx("span", { "data-slot": "project-list-name", className: "text-sm font-semibold", children: project.name }), project.summary === undefined ? null : (_jsx("span", { className: "text-muted-foreground text-pretty text-sm", children: cellOf('summary', project) })), project.tags === undefined ? null : (_jsx("span", { "data-slot": "project-list-tags", className: "flex flex-wrap items-center gap-1.5", children: project.tags.map((tag) => (_jsx(Tag, { label: tag.label }, tag.id))) })), project.progress === undefined ? null : (_jsx("div", { "data-slot": "project-list-progress", className: "max-w-64 pt-1", children: _jsx(Progress, { value: project.progress, valueText: project.progressLabel?.(project.progress, project.name) }) }))] }), _jsxs("div", { className: "flex shrink-0 flex-col items-start gap-2 sm:items-end", children: [cellOf('state', project), cellOf('owner', project), cellOf('updated', project), cellOf('href', project)] })] }, project.id))) }));
+    return (_jsx(Section, { "data-slot": "project-list-01", "data-variant": variant, className: cn(className), children: _jsxs("div", { className: "flex flex-col gap-8", children: [heading, _jsxs("div", { "data-slot": "project-list-body", className: cn(
+                    // The two arrangements get one display each rather than a base and an
+                    // override, because `flex` and `grid` are the same property and which
+                    // one wins is a question about the generated stylesheet rather than
+                    // about the order of the class names here.
+                    filters === undefined ? 'flex flex-col gap-6' : 'flex flex-col gap-6 lg:flex-row lg:items-start lg:gap-10'), children: [filters === undefined ? null : (_jsx("div", { "data-slot": "project-list-filters", className: "w-full shrink-0 lg:max-w-72", children: filters })), _jsxs("div", { "data-slot": "project-list-main", className: "flex min-w-0 flex-1 flex-col gap-4", children: [toolbar === undefined ? null : (_jsx("div", { "data-slot": "project-list-toolbar", className: "flex flex-wrap items-center gap-2", children: toolbar })), list, footer === undefined ? null : (_jsx("div", { "data-slot": "project-list-footer", className: "flex flex-wrap items-center gap-3", children: footer }))] })] })] }) }));
+}
+export default ProjectList01;

package/dist/blocks/provisioning-01/index.d.ts

@@ -0,0 +1,3 @@
+export { Provisioning01, default } from './provisioning.js';
+export type { Provisioning01Props, Provisioning01Status, ProvisioningField, ProvisioningFieldType, ProvisioningOption, ProvisioningStep, ProvisioningValue, } from './provisioning.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/blocks/provisioning-01/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/blocks/provisioning-01/index.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAA;AAOxD,YAAY,EACV,mBAAmB,EACnB,oBAAoB,EACpB,iBAAiB,EACjB,qBAAqB,EACrB,kBAAkB,EAClB,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,gBAAgB,CAAA"}

package/dist/blocks/provisioning-01/index.js

@@ -0,0 +1 @@
+export { Provisioning01, default } from './provisioning.js';