@nanisoft/prism-ui 0.13.0 → 0.15.0

package/dist/blocks/trend-01/trend.js

@@ -0,0 +1,99 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { CtaLink } from '../../components/ui/cta-link.js';
+import { Metric } from '../../components/ui/metric.js';
+import { Section, SectionHeading } from '../../components/ui/section.js';
+import { Sparkline } from '../../components/ui/sparkline.js';
+import { cn } from '../../lib/utils.js';
+/**
+ * A ranked list of rising values: a name, a current reading, the change against
+ * the previous one, and a small series beside it.
+ *
+ * **A trend row is a metric with a shape beside it, so the Block composes
+ * `Metric` and `Sparkline` rather than drawing either of them.** Both halves of
+ * that sentence are load-bearing. `Metric` owns the arrangement a headline figure
+ * is read in, which puts the figure first and the name under it, and it owns the
+ * three things a hand-rolled version of that gets wrong: that the direction is
+ * derived from the sign of the number rather than declared beside it, that the
+ * rising mark is a glyph so assistive technology names it in the reader's own
+ * language rather than through an English `aria-label`, and that a string value
+ * is set in the mono face while a composed one is not. `Sparkline` owns the shape
+ * and, more importantly, owns the fact that the numbers behind the shape are in
+ * the document: a ninety-six pixel line with no axis is a picture a reader cannot
+ * query, so the Component renders the same array as a table a screen reader can
+ * walk and a crawler can index. A Block that hand-rolled either would be a second
+ * implementation of a Component that already owns it, and the second
+ * implementation would be the one without the table, because the table is the part
+ * nobody draws by hand and it is the part that matters.
+ *
+ * **`deltaLabel` is required whenever any row carries a `delta`, and the reason
+ * is that the Block cannot know which of three sentences the caller means.**
+ * "up 12 percent", "+12%" and "12 higher than last week" are three sentences
+ * about one number, and they are not formats of one another: the first is a
+ * phrase with a unit, the second is a signed figure for a reader who is already
+ * looking at a number, and the third is a comparison against a named period that
+ * a reader who cannot see the period will misread as a comparison against
+ * whatever they assumed. Worse, the fallback a Block would reach for is the worst
+ * of the three, because a bare "+12" printed beside a figure is a number with an
+ * arithmetic symbol on it, and a screen reader reads that as a formula rather
+ * than as a change. So the prop is required and the Block throws without it
+ * rather than printing the sign itself, and the cost of the throw is that a
+ * caller who genuinely has no unit has to write the formatter that says so.
+ *
+ * **`seriesLabel` is required whenever any row carries a `series`, for the reason
+ * the `Sparkline` JSDoc gives in full: a figure with no name is not announced
+ * and not linkable.** A trend list is a column of small pictures, and a column of
+ * unnamed pictures is a column of shapes a reader has to guess the meaning of from
+ * the number beside them, which is the guess the whole figure exists to remove.
+ * Two rows whose series are both "the last thirty days" and one row whose series
+ * is the same thirty days as a percentage are three pictures that look identical
+ * and mean three things, and only a name tells them apart.
+ *
+ * **The order is the caller's, and there is deliberately no `sort`.** A trend list
+ * is ranked, and the rank is the Block's premise, but the Block cannot see what
+ * it is ranking by: the caller may have ranked by the delta, by the current value,
+ * by a measure of their own that is not in the data at all, or by nothing at all
+ * because the list is a hand-picked set of five. A `sort` prop would have to name
+ * a key, and any key it named would be wrong for at least one of those four
+ * callers, and the failure would be silent: a list sorted by the wrong column
+ * still looks ranked. The other answer, deriving the order from the data, is
+ * worse, because it makes this Block 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. So the
+ * rank is the position in the array, the ordinal is drawn from it, and the caller
+ * holds the one claim that ordering a ranked list makes.
+ *
+ * **The rows are one `<ol>`.** A list that was split by a cap, or by a variant,
+ * or by whether a row had a series, would be several lists and a screen reader
+ * would announce it as several. The cap shortens the list rather than dividing it,
+ * and a row with no series is a shorter row, not a different kind of row.
+ *
+ * It is a server Component: no hook, no state, no client code and no router. The
+ * two Components it composes are both server Components, so a trend list costs a
+ * consumer nothing in client JavaScript.
+ */
+export function Trend01({ eyebrow, title, description, items, limit, empty, headingLevel = 'h2', className, }) {
+    for (const item of items) {
+        if (item.delta !== undefined && !item.deltaLabel) {
+            throw new Error('Trend01: an item carries a delta with no deltaLabel, so the change would print as a signed ' +
+                'number beside a figure, which a screen reader reads as a formula. Pass the words for the ' +
+                'change, or drop the delta and let the row carry the reading alone.');
+        }
+        if (item.series !== undefined && !item.seriesLabel) {
+            throw new Error('Trend01: an item carries a series with no seriesLabel, so the shape beside the figure would be ' +
+                'an unnamed picture. A figure with no name is not announced. Pass what the series is.');
+        }
+        if (item.href !== undefined && !item.hrefLabel) {
+            throw new Error('Trend01: an item carries an href with no hrefLabel, so the link would be announced by its ' +
+                'destination alone. A space name is a name, and the sentence saying that following the link ' +
+                'is a thing you can do belongs to the caller.');
+        }
+    }
+    const shown = items.slice(0, limit ?? items.length);
+    if (shown.length === 0) {
+        if (empty === undefined)
+            return null;
+        return (_jsxs(Section, { className: className, children: [_jsx(SectionHeading, { as: headingLevel, align: "left", eyebrow: eyebrow, title: title, description: description }), _jsx("div", { "data-slot": "trend-empty", className: "text-muted-foreground text-pretty text-sm", children: empty })] }));
+    }
+    return (_jsxs(Section, { children: [_jsx(SectionHeading, { as: headingLevel, align: "left", eyebrow: eyebrow, title: title, description: description, className: "mb-10" }), _jsx("ol", { "data-slot": "trend-list", className: cn('flex flex-col', className), children: shown.map((item, index) => (_jsxs("li", { "data-slot": "trend-row", "data-has-series": item.series === undefined ? undefined : true, className: "border-border flex flex-wrap items-center justify-between gap-x-6 gap-y-3 border-b py-4 first:border-t", children: [_jsx("span", { "data-slot": "trend-rank", className: "text-muted-foreground w-6 shrink-0 font-mono text-xs tabular-nums", children: String(index + 1).padStart(2, '0') }), _jsx(Metric, { className: "min-w-0 flex-1", value: item.value, label: item.label, delta: item.delta, deltaFormat: item.deltaLabel }), item.series !== undefined || item.href !== undefined ? (_jsxs("div", { "data-slot": "trend-row-end", className: "flex shrink-0 items-center gap-4", children: [item.series !== undefined && item.seriesLabel !== undefined ? (_jsx(Sparkline, { values: item.series, label: item.seriesLabel })) : null, item.href !== undefined && item.hrefLabel !== undefined ? (_jsx(CtaLink, { href: item.href, size: "sm", variant: "ghost", children: item.hrefLabel })) : null] })) : null] }, item.id))) })] }));
+}
+export default Trend01;

package/dist/blocks/trust-strip-01/index.d.ts

@@ -0,0 +1,3 @@
+export { TrustStrip01, default } from './trust-strip-01.js';
+export type { TrustStripItem, TrustStrip01Props } from './trust-strip-01.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/blocks/trust-strip-01/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/blocks/trust-strip-01/index.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAA;AAIxD,YAAY,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA"}

package/dist/blocks/trust-strip-01/index.js

@@ -0,0 +1 @@
+export { TrustStrip01, default } from './trust-strip-01.js';

package/dist/blocks/trust-strip-01/trust-strip-01.d.ts

@@ -0,0 +1,139 @@
+import type { LucideIcon } from 'lucide-react';
+import { type HeadingLevel } from '../../components/ui/section.js';
+/**
+ * One assurance statement, and the mark that carries it.
+ *
+ * The icon is required and not optional, because this item is always rendered: an
+ * optional icon would compile and then paint an empty accent tile, which is the
+ * safe-at-render condition an optional prop turns unsafe. The icon is `aria-hidden`
+ * at the render, because the label beside it is the statement and a reader who
+ * cannot see the mark has not been told anything by it.
+ *
+ * `detail` is optional and additive: a strip item with a detail renders both lines and
+ * one without it renders one, with no space held open for the second.
+ */
+export type TrustStripItem = {
+    /** The mark beside the statement. Hidden from assistive technology. */
+    icon: LucideIcon;
+    /** The statement itself. A few words, read in one glance. */
+    label: string;
+    /** The qualifier under the statement, for the detail a bare statement cannot carry. */
+    detail?: string;
+};
+/**
+ * The props a TrustStrip01 takes.
+ *
+ * Every string is a prop and the Block ships none. There is no default list of
+ * certifications, no default compliance marks and no default customer count, and the
+ * reason is on the Block's own JSDoc: all three are claims, and a claim is the one
+ * thing this frame is not allowed to make on a consumer's behalf.
+ */
+export type TrustStrip01Props = {
+    /**
+     * The statements, in the order a reader should meet them. Order is the caller's
+     * because it is a claim about which assurance matters most.
+     */
+    items: readonly TrustStripItem[];
+    /**
+     * Where the band sits in the container.
+     *
+     * `center` is the usual one, because the band is usually centred under a hero and a
+     * centred band under a centred hero is the same axis. `left` is for a page whose
+     * hero is flush left, where a centred strip under it reads as a different
+     * composition rather than as a band.
+     *
+     * @defaultValue 'center'
+     */
+    align?: 'center' | 'left';
+    /**
+     * The surface the band is drawn on.
+     *
+     * `default` leaves it on the page ground, which is the quieter of the two and the
+     * right one above the fold where the strip's job is to be noticed once and not
+     * again. `muted` puts the band on the muted surface, for a strip that is a section
+     * in its own right rather than a transition. The muted band states its own ink as
+     * well as its own fill, which is the rule `check-variant-ink` and `toast.tsx` both
+     * state: a surface that sets a fill and inherits its ink is correct wherever the
+     * design system happened to put it and wrong everywhere else.
+     *
+     * @defaultValue 'default'
+     */
+    tone?: 'default' | 'muted';
+    /**
+     * The band's name, used as a heading that is in the outline and not on the page.
+     *
+     * Optional, and it is the only way this Block renders a heading at all: a visible
+     * heading above a strip of four assurance lines is a heading about a heading, which
+     * is the arrangement `LogoStrip01` refuses. But a strip is often one item among a
+     * page of sections, and a reader navigating by heading then finds nothing where the
+     * band is, which is a gap in the outline rather than a virtue. So the name is
+     * available and hidden: a reader who navigates by heading meets it, and a reader
+     * reading the page sees the four lines and no title over them.
+     */
+    heading?: string;
+    /**
+     * The level that hidden heading is composed at.
+     *
+     * It names the level of the one heading this Block can render, and it does nothing
+     * when no `heading` is passed. That is the same pair `LogoStrip01` declares for its
+     * `title`, and the default is `h2` because a Block is composed rather than a page:
+     * it installs into a consumer's layout and renders inside catalogue previews, where
+     * the surrounding document already owns the `h1`. See `HeadingLevel`.
+     *
+     * @defaultValue 'h2'
+     */
+    headingLevel?: HeadingLevel;
+    /**
+     * Layout only, exactly as on every Component. Changing a Prism-owned visual
+     * property from here is prohibited.
+     */
+    className?: string;
+};
+/**
+ * A narrow band of short assurance statements, one per mark, with no visible heading.
+ *
+ * **This is the most common place on a marketing page where a design system is
+ * tempted to put a claim, and the narrowness of what an honest Block can say here is
+ * the whole reason the Item is worth shipping.** A strip of badges reads as free
+ * assurance: it looks like furniture, the way a claim looks when it is made by
+ * something nobody can ask. So the obvious version of this Block ships a row of
+ * certifications and a row of customer logos, which every consumer of the library
+ * would then publish as NaniSoft's own. Prism ships the frame and the caller ships
+ * the words, and a strip of certifications, a strip of compliance marks and a strip
+ * of a customer count are then the same component and none of them is Prism's to
+ * assert. The strip is deliberately narrow: it takes an icon and a label per item and
+ * it has nowhere to put a claim of its own.
+ *
+ * **It is not a `logo` cloud, and the difference is evidence against assertion.** A
+ * name beside a mark is evidence: the reader can look the organisation up, and the
+ * arrangement is checkable by anyone, which is what makes a customer strip honest.
+ * A sentence beside a mark is a claim, and a claim is not checkable by looking.
+ * `LogoCloud01` is the other Block and it takes marks rather than sentences, so a
+ * page that has real marks to show uses that one and a page that has real statements
+ * to make uses this one. Shipping one component for both would have meant shipping one
+ * of the two as an afterthought, and the strip shape is the right home for a
+ * sentence.
+ *
+ * **The icons are hidden from assistive technology.** The label beside a mark is the
+ * statement, and a reader who cannot see the mark has learned nothing from the mark,
+ * so announcing it would replace the words with the thing the words are there to
+ * avoid. The same warning applies to the printed band: a mark whose meaning is its
+ * shape does not survive a monochrome printer, and the label is what carries it there.
+ *
+ * **The band is a `ul`, and it renders nothing for an empty list.** A reader is told
+ * how many statements there are before hearing the first one, which is the whole
+ * answer to the question a strip raises, and a caller with nothing to assert gets no
+ * frame rather than a bordered box with nothing in it.
+ *
+ * **The strip does not move.** A band of items that slides is an entrance animation,
+ * and this system has none: motion is a response to something the reader did, or a
+ * cycle that is making a claim about a running system, and neither is a row of
+ * assurance lines arriving. Four NaniSoft sites wanted their strips to move; what they
+ * wanted from the movement was a second, quieter statement of what the product is,
+ * and repetition of the type does that without anything moving.
+ *
+ * It is a server Component: no hook, no state and no client code.
+ */
+export declare function TrustStrip01({ items, align, tone, heading, headingLevel, className, }: TrustStrip01Props): import("react").JSX.Element | null;
+export default TrustStrip01;
+//# sourceMappingURL=trust-strip-01.d.ts.map

package/dist/blocks/trust-strip-01/trust-strip-01.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trust-strip-01.d.ts","sourceRoot":"","sources":["../../../src/blocks/trust-strip-01/trust-strip-01.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAE9C,OAAO,EAAW,KAAK,YAAY,EAAE,MAAM,6BAA6B,CAAA;AAIxE;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,uEAAuE;IACvE,IAAI,EAAE,UAAU,CAAA;IAChB,6DAA6D;IAC7D,KAAK,EAAE,MAAM,CAAA;IACb,uFAAuF;IACvF,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB,CAAA;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B;;;OAGG;IACH,KAAK,EAAE,SAAS,cAAc,EAAE,CAAA;IAChC;;;;;;;;;OASG;IACH,KAAK,CAAC,EAAE,QAAQ,GAAG,MAAM,CAAA;IACzB;;;;;;;;;;;;OAYG;IACH,IAAI,CAAC,EAAE,SAAS,GAAG,OAAO,CAAA;IAC1B;;;;;;;;;;OAUG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;;;;;;;;OAUG;IACH,YAAY,CAAC,EAAE,YAAY,CAAA;IAC3B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,wBAAgB,YAAY,CAAC,EAC3B,KAAK,EACL,KAAgB,EAChB,IAAgB,EAChB,OAAO,EACP,YAAmB,EACnB,SAAS,GACV,EAAE,iBAAiB,sCA2DnB;AAED,eAAe,YAAY,CAAA"}

package/dist/blocks/trust-strip-01/trust-strip-01.js

@@ -0,0 +1,58 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Section } from '../../components/ui/section.js';
+import { Heading } from '../../components/ui/typography.js';
+import { cn } from '../../lib/utils.js';
+/**
+ * A narrow band of short assurance statements, one per mark, with no visible heading.
+ *
+ * **This is the most common place on a marketing page where a design system is
+ * tempted to put a claim, and the narrowness of what an honest Block can say here is
+ * the whole reason the Item is worth shipping.** A strip of badges reads as free
+ * assurance: it looks like furniture, the way a claim looks when it is made by
+ * something nobody can ask. So the obvious version of this Block ships a row of
+ * certifications and a row of customer logos, which every consumer of the library
+ * would then publish as NaniSoft's own. Prism ships the frame and the caller ships
+ * the words, and a strip of certifications, a strip of compliance marks and a strip
+ * of a customer count are then the same component and none of them is Prism's to
+ * assert. The strip is deliberately narrow: it takes an icon and a label per item and
+ * it has nowhere to put a claim of its own.
+ *
+ * **It is not a `logo` cloud, and the difference is evidence against assertion.** A
+ * name beside a mark is evidence: the reader can look the organisation up, and the
+ * arrangement is checkable by anyone, which is what makes a customer strip honest.
+ * A sentence beside a mark is a claim, and a claim is not checkable by looking.
+ * `LogoCloud01` is the other Block and it takes marks rather than sentences, so a
+ * page that has real marks to show uses that one and a page that has real statements
+ * to make uses this one. Shipping one component for both would have meant shipping one
+ * of the two as an afterthought, and the strip shape is the right home for a
+ * sentence.
+ *
+ * **The icons are hidden from assistive technology.** The label beside a mark is the
+ * statement, and a reader who cannot see the mark has learned nothing from the mark,
+ * so announcing it would replace the words with the thing the words are there to
+ * avoid. The same warning applies to the printed band: a mark whose meaning is its
+ * shape does not survive a monochrome printer, and the label is what carries it there.
+ *
+ * **The band is a `ul`, and it renders nothing for an empty list.** A reader is told
+ * how many statements there are before hearing the first one, which is the whole
+ * answer to the question a strip raises, and a caller with nothing to assert gets no
+ * frame rather than a bordered box with nothing in it.
+ *
+ * **The strip does not move.** A band of items that slides is an entrance animation,
+ * and this system has none: motion is a response to something the reader did, or a
+ * cycle that is making a claim about a running system, and neither is a row of
+ * assurance lines arriving. Four NaniSoft sites wanted their strips to move; what they
+ * wanted from the movement was a second, quieter statement of what the product is,
+ * and repetition of the type does that without anything moving.
+ *
+ * It is a server Component: no hook, no state and no client code.
+ */
+export function TrustStrip01({ items, align = 'center', tone = 'default', heading, headingLevel = 'h2', className, }) {
+    if (items.length === 0)
+        return null;
+    const centred = align === 'center';
+    return (_jsxs(Section, { "data-slot": "trust-strip-01", className: "py-10 sm:py-14", children: [heading ? (_jsx(Heading, { as: headingLevel, "data-slot": "trust-strip-01-heading", className: "sr-only", children: heading })) : null, _jsx("ul", { "data-slot": "trust-strip", className: cn('flex flex-wrap items-center gap-x-8 gap-y-5 text-sm', centred ? 'justify-center text-center' : 'justify-start text-left', tone === 'muted' ? 'bg-muted text-foreground rounded-xl px-6 py-6' : 'text-foreground', className), children: items.map((item) => (_jsxs("li", { "data-slot": "trust-strip-01-item", className: "flex items-center gap-3 text-left", children: [_jsx("span", { "aria-hidden": true, "data-slot": "trust-strip-01-icon", className: cn('flex size-8 shrink-0 items-center justify-center rounded-lg', tone === 'muted'
+                                ? 'bg-background text-muted-foreground'
+                                : 'bg-muted text-muted-foreground'), children: _jsx(item.icon, { className: "size-4" }) }), _jsxs("span", { className: "flex flex-col", children: [_jsx("span", { className: "font-medium", children: item.label }), item.detail ? (_jsx("span", { "data-slot": "trust-strip-01-detail", className: "text-muted-foreground text-xs", children: item.detail })) : null] })] }, item.label))) })] }));
+}
+export default TrustStrip01;

package/dist/blocks/two-factor-01/index.d.ts

@@ -0,0 +1,3 @@
+export { TwoFactor01, default } from './two-factor-01.js';
+export type { TwoFactor01Cancel, TwoFactor01Code, TwoFactor01Method, TwoFactor01Props, TwoFactor01Remember, TwoFactor01Resend, TwoFactor01Status, } from './two-factor-01.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/blocks/two-factor-01/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/blocks/two-factor-01/index.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAA;AAMtD,YAAY,EACV,iBAAiB,EACjB,eAAe,EACf,iBAAiB,EACjB,gBAAgB,EAChB,mBAAmB,EACnB,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,iBAAiB,CAAA"}

package/dist/blocks/two-factor-01/index.js

@@ -0,0 +1 @@
+export { TwoFactor01, default } from './two-factor-01.js';