@nanisoft/prism-ui 0.13.0 → 0.16.0

package/dist/blocks/chart-group-01/index.d.ts

@@ -0,0 +1,3 @@
+export { ChartGroup01, default } from './chart-group-01.js';
+export type { ChartGroup01Card, ChartGroup01Props } from './chart-group-01.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/blocks/chart-group-01/index.d.ts.map

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

package/dist/blocks/chart-group-01/index.js

@@ -0,0 +1 @@
+export { ChartGroup01, default } from './chart-group-01.js';

package/dist/blocks/code-sample-01/code-sample.d.ts

@@ -0,0 +1,193 @@
+import type { ReactNode } from 'react';
+import { type HeadingLevel } from '../../components/ui/section.js';
+/**
+ * The half of the props every sample carries, whichever arm of the name union it
+ * is in.
+ *
+ * Declared apart from the union so the two arms below are two arms rather than
+ * two copies of the same six fields, and so a field added here is added once.
+ */
+type CodeSample01Figure = {
+    /**
+     * What the sample is called.
+     *
+     * Required, and the reason is the difference between a sample and a snippet. A
+     * snippet is a piece of code with a sentence around it; a sample is something a
+     * document refers to, names in its own table of contents, and sends a reader to
+     * from another page. A sample with no title is a code block the reader cannot
+     * refer to, so there is nothing to put in the contents, nothing to link to, and
+     * nothing for the rest of the document to say when it needs the same code again.
+     */
+    title: ReactNode;
+    /**
+     * The sentence under the title, about what this particular code shows.
+     *
+     * A node, and the reason it is a node rather than a string is that it is often
+     * not prose: it is a link to the page that explains the whole idea, a list of
+     * three things to notice in it, or a `<p>` a caller wrote in their own Markdown
+     * pipeline. The Block draws it in the heading's own description slot, so it
+     * inherits that type size rather than bringing a second one.
+     */
+    description?: ReactNode;
+    /**
+     * The source, exactly as it is in the file.
+     *
+     * A string and not a `ReactNode`, for `CodeBlock`'s reason and not this Block's:
+     * the claim a code sample makes is that what a reader copies is what the caller
+     * holds, and a node would be markup between the two.
+     */
+    code: string;
+    /**
+     * The language, in whatever form the caller's own documentation uses it. Drawn
+     * in the code surface's own header.
+     */
+    language?: string;
+    /** The file the snippet is from, drawn in the code surface's own header. */
+    filename?: string;
+    /**
+     * Draws a number against each line, in the gutter beside the code and not in
+     * the copied text.
+     */
+    lineNumbers?: boolean;
+    /**
+     * How the sample is placed: a section of its own, or a band inside a section
+     * the caller already owns.
+     *
+     * @defaultValue 'section'
+     */
+    layout?: 'section' | 'inline';
+    /** Heading level for the sample's title. See `HeadingLevel`. */
+    headingLevel?: HeadingLevel;
+    /**
+     * A short label above the title, in the position every other Block puts one.
+     *
+     * Present because this Block composes `SectionHeading` and every Block that
+     * composes it takes one, not because a code sample needs an eyebrow more than a
+     * feature grid does. An earlier version of this omitted it and the Demo passed
+     * one anyway, which is the ordinary way an inconsistency between a Block and
+     * the family it joined gets found.
+     */
+    eyebrow?: ReactNode;
+    /**
+     * Layout only, exactly as on every Block. Changing a Prism-owned visual
+     * property from here is prohibited.
+     */
+    className?: string;
+};
+/**
+ * The props a CodeSample01 takes.
+ *
+ * **The name is a union and not `label?: string`, and the reason is
+ * `CodeBlockProps`'s, inherited rather than re-invented.** `code-block` already
+ * draws that rule: a figure with no accessible name and a control beside it is a
+ * button that acts on something a reader cannot identify, so the name is required
+ * in the arm that takes `actions` and optional in the arm that does not, and the
+ * type makes the second case impossible to reach by accident. This Block holds the
+ * same union and forwards it, because a Block that flattened it would be a Block
+ * that could hand `code-block` an unnamed figure with a copy control on it, and the
+ * only thing it would have added is a way to do that.
+ *
+ * **A sample with no `title` is a snippet, and the difference is why this is a
+ * Block at all.** A snippet is a piece of code inside a sentence, and `CodeBlock`
+ * is the right thing for it. A sample is a titled thing in a document: a name, a
+ * sentence saying what the code shows, and the controls that act on it. That band
+ * appears forty times in one documentation site, and each of those forty is
+ * currently hand-written in four repositories, which is four copies of a heading
+ * above a code surface and four places to forget the gutter.
+ */
+export type CodeSample01Props = CodeSample01Figure & ({
+    /**
+     * The figure's accessible name, and the only name the snippet has. A path,
+     * a command, the thing the snippet shows.
+     */
+    label: string;
+    /**
+     * The caller's own controls for this sample, drawn in the code surface's
+     * header.
+     *
+     * A slot and not a copy button, and the reason is `code-block`'s and this
+     * package's: this package ships no word a consumer cannot localise, and a
+     * copy control is the clearest case of one. Whatever the caller puts here
+     * keeps its own accessible name, its own focus order and its own state, and
+     * the name of that control is the caller's and not Prism's.
+     */
+    actions?: ReactNode;
+} | {
+    /**
+     * The figure's accessible name. Optional here, and only here, because a
+     * sample with no control beside it is identified by the title above it.
+     */
+    label?: string;
+    /** A sample with no control beside it has no slot to fill. */
+    actions?: never;
+});
+/**
+ * A titled code sample: a name, a sentence about what the code shows, the code in
+ * `CodeBlock`, and the caller's own controls in its header.
+ *
+ * **This is a Block and `code-block` is a Component, and the difference is the
+ * band around the surface rather than the surface.** `code-block` owns the tinted
+ * mono surface, the header for the machine words, the gutter and the line count. It
+ * owns no title, no sentence about what the code is for, and no place to put the
+ * controls, and those three are what a document puts on either side of a snippet.
+ * So the Item here is the section that holds all of them: a name, a sentence, a
+ * surface, and a header with the caller's control on it. The argument for shipping
+ * it is a count. One documentation site has forty of these bands, and before this
+ * Item each of the forty was hand-written, which means forty copies of a heading
+ * above a code surface, forty places to forget the gutter on the one sample where
+ * a line number matters, and forty places where a copy control's accessible name
+ * was written in whatever language the author was in that week. Composing
+ * `CodeBlock` rather than re-deriving the surface is the other half of it: the
+ * surface is where the copy has to be clean, where the gutter has to stay out of
+ * the clipboard, and where the header is a header and not an empty strip, and
+ * re-deriving it here would have been a second implementation of a decision this
+ * package has already made once and would have to defend twice.
+ *
+ * **`layout` is a prop because a documentation page and an application page need
+ * different things from the same band.** A page that owns its own sections composes
+ * a Page, and a Page is a composition of Blocks: a Page that has four samples in
+ * it and no section rhythm between them is a Page whose samples float. So `section`
+ * draws a `Section` and a Page composes four of these and gets four bands of
+ * vertical rhythm for free. An application page that wants a sample inside a panel
+ * it already draws passes `inline`, which is the same heading and the same surface
+ * with no container and no rhythm of its own, and `className` is where a caller
+ * puts the space. The alternative was two Items, and a Component and a Block that
+ * differ only in whether they render a `Section` are one Item with a prop: the
+ * heading, the surface and the controls are identical in both, and splitting them
+ * would have given the corpus two entries describing one arrangement twice.
+ *
+ * **The title is required and it is the heading of the section, at
+ * `headingLevel`.** A sample with no title is a snippet, and a snippet is
+ * `CodeBlock`: a piece of code with a sentence around it. What makes a sample a
+ * sample is that the document can refer to it, and a thing the document cannot
+ * name is a thing the contents cannot list, another page cannot link to, and a
+ * reader cannot be told to go and look at. So the title is required, it is the
+ * heading, and the level is a prop so a sample composed inside a Page that already
+ * has a heading for the same content takes one level deeper.
+ *
+ * **The name union is `code-block`'s, forwarded whole, and the run refuses a
+ * mismatch the type should have caught.** A sample with a control beside it and no
+ * accessible name is a control acting on something a reader cannot identify, and
+ * the diagnostic says so rather than rendering one. It is unreachable from
+ * TypeScript and that is exactly why it is written: a caller arriving from
+ * JavaScript, from a spread of an object typed as `Record<string, unknown>`, or
+ * from a type they widened themselves gets the same answer as a caller who made a
+ * mistake in TypeScript, and the answer names the prop.
+ *
+ * **Nothing here is a code highlighter, and that refusal is inherited rather than
+ * re-decided.** `CodeBlock` argues it at length: a highlighter is a second answer
+ * to what a token means, in its own vocabulary, published as a theme and styled
+ * with class names that have to be reconciled against six packs and two modes. A
+ * caller who has decided they want highlighting wraps this Block's `code` in their
+ * own, and the two places to do it are the `actions` slot and the `code` string
+ * itself. The cost of the refusal is a wall of one colour, and the mitigation is
+ * the table of contents the gutter and the filename are: a reader looking for a
+ * name scans the left edge and the header rather than hunting for a hue.
+ *
+ * It is a server Component: no hook, no state and no client code. The caller's
+ * `actions` may be a client Component, in which case that control is the only
+ * client code in the band, and it is the caller's.
+ */
+export declare function CodeSample01(props: CodeSample01Props): import("react").JSX.Element;
+export default CodeSample01;
+//# sourceMappingURL=code-sample.d.ts.map

package/dist/blocks/code-sample-01/code-sample.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"code-sample.d.ts","sourceRoot":"","sources":["../../../src/blocks/code-sample-01/code-sample.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAGtC,OAAO,EAA2B,KAAK,YAAY,EAAE,MAAM,6BAA6B,CAAA;AAGxF;;;;;;GAMG;AACH,KAAK,kBAAkB,GAAG;IACxB;;;;;;;;;OASG;IACH,KAAK,EAAE,SAAS,CAAA;IAChB;;;;;;;;OAQG;IACH,WAAW,CAAC,EAAE,SAAS,CAAA;IACvB;;;;;;OAMG;IACH,IAAI,EAAE,MAAM,CAAA;IACZ;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;OAGG;IACH,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAA;IAC7B,gEAAgE;IAChE,YAAY,CAAC,EAAE,YAAY,CAAA;IAC3B;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,SAAS,CAAA;IACnB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,MAAM,iBAAiB,GAAG,kBAAkB,GAChD,CACI;IACE;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAA;IACb;;;;;;;;;OASG;IACH,OAAO,CAAC,EAAE,SAAS,CAAA;CACpB,GACD;IACE;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,8DAA8D;IAC9D,OAAO,CAAC,EAAE,KAAK,CAAA;CAChB,CACJ,CAAA;AAoBH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkEG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,iBAAiB,+BAoCpD;AAED,eAAe,YAAY,CAAA"}

package/dist/blocks/code-sample-01/code-sample.js

@@ -0,0 +1,104 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { CodeBlock } from '../../components/ui/code-block.js';
+import { Section, SectionHeading } from '../../components/ui/section.js';
+import { cn } from '../../lib/utils.js';
+/**
+ * The accessible name a figure with controls beside it has to have, or the refusal.
+ *
+ * Reached only by a caller who got the type wrong, and the reason it is still here
+ * rather than a cast is that a cast would be the library quietly making a claim
+ * about a caller's code. The message names the prop and says what the name is for.
+ */
+function named(name) {
+    if (name === undefined) {
+        throw new Error('CodeSample01: the sample passed an actions slot with no label, so the code surface would be a figure with ' +
+            'no accessible name and the control beside it would act on something a reader cannot identify. Pass the ' +
+            'path, the command, or the thing the snippet shows.');
+    }
+    return name;
+}
+/**
+ * A titled code sample: a name, a sentence about what the code shows, the code in
+ * `CodeBlock`, and the caller's own controls in its header.
+ *
+ * **This is a Block and `code-block` is a Component, and the difference is the
+ * band around the surface rather than the surface.** `code-block` owns the tinted
+ * mono surface, the header for the machine words, the gutter and the line count. It
+ * owns no title, no sentence about what the code is for, and no place to put the
+ * controls, and those three are what a document puts on either side of a snippet.
+ * So the Item here is the section that holds all of them: a name, a sentence, a
+ * surface, and a header with the caller's control on it. The argument for shipping
+ * it is a count. One documentation site has forty of these bands, and before this
+ * Item each of the forty was hand-written, which means forty copies of a heading
+ * above a code surface, forty places to forget the gutter on the one sample where
+ * a line number matters, and forty places where a copy control's accessible name
+ * was written in whatever language the author was in that week. Composing
+ * `CodeBlock` rather than re-deriving the surface is the other half of it: the
+ * surface is where the copy has to be clean, where the gutter has to stay out of
+ * the clipboard, and where the header is a header and not an empty strip, and
+ * re-deriving it here would have been a second implementation of a decision this
+ * package has already made once and would have to defend twice.
+ *
+ * **`layout` is a prop because a documentation page and an application page need
+ * different things from the same band.** A page that owns its own sections composes
+ * a Page, and a Page is a composition of Blocks: a Page that has four samples in
+ * it and no section rhythm between them is a Page whose samples float. So `section`
+ * draws a `Section` and a Page composes four of these and gets four bands of
+ * vertical rhythm for free. An application page that wants a sample inside a panel
+ * it already draws passes `inline`, which is the same heading and the same surface
+ * with no container and no rhythm of its own, and `className` is where a caller
+ * puts the space. The alternative was two Items, and a Component and a Block that
+ * differ only in whether they render a `Section` are one Item with a prop: the
+ * heading, the surface and the controls are identical in both, and splitting them
+ * would have given the corpus two entries describing one arrangement twice.
+ *
+ * **The title is required and it is the heading of the section, at
+ * `headingLevel`.** A sample with no title is a snippet, and a snippet is
+ * `CodeBlock`: a piece of code with a sentence around it. What makes a sample a
+ * sample is that the document can refer to it, and a thing the document cannot
+ * name is a thing the contents cannot list, another page cannot link to, and a
+ * reader cannot be told to go and look at. So the title is required, it is the
+ * heading, and the level is a prop so a sample composed inside a Page that already
+ * has a heading for the same content takes one level deeper.
+ *
+ * **The name union is `code-block`'s, forwarded whole, and the run refuses a
+ * mismatch the type should have caught.** A sample with a control beside it and no
+ * accessible name is a control acting on something a reader cannot identify, and
+ * the diagnostic says so rather than rendering one. It is unreachable from
+ * TypeScript and that is exactly why it is written: a caller arriving from
+ * JavaScript, from a spread of an object typed as `Record<string, unknown>`, or
+ * from a type they widened themselves gets the same answer as a caller who made a
+ * mistake in TypeScript, and the answer names the prop.
+ *
+ * **Nothing here is a code highlighter, and that refusal is inherited rather than
+ * re-decided.** `CodeBlock` argues it at length: a highlighter is a second answer
+ * to what a token means, in its own vocabulary, published as a theme and styled
+ * with class names that have to be reconciled against six packs and two modes. A
+ * caller who has decided they want highlighting wraps this Block's `code` in their
+ * own, and the two places to do it are the `actions` slot and the `code` string
+ * itself. The cost of the refusal is a wall of one colour, and the mitigation is
+ * the table of contents the gutter and the filename are: a reader looking for a
+ * name scans the left edge and the header rather than hunting for a hue.
+ *
+ * It is a server Component: no hook, no state and no client code. The caller's
+ * `actions` may be a client Component, in which case that control is the only
+ * client code in the band, and it is the caller's.
+ */
+export function CodeSample01(props) {
+    const { title, description, code, language, filename, lineNumbers, layout = 'section', headingLevel = 'h2', eyebrow, className, } = props;
+    // The union forwarded whole rather than flattened, so `code-block` is the one
+    // place in this package that decides what a figure with a control beside it has
+    // to carry. The two arms are spelled out because a Block that restated the rule
+    // as `label?: string` would be a second place to get it wrong.
+    const figure = props.actions === undefined
+        ? { code, language, filename, lineNumbers, label: props.label }
+        : { code, language, filename, lineNumbers, label: named(props.label), actions: props.actions };
+    const sample = (_jsxs("div", { "data-slot": "code-sample-01", "data-layout": layout, className: cn('flex flex-col gap-6', className), children: [_jsx(SectionHeading, { as: headingLevel, align: "left", eyebrow: eyebrow, title: title, description: description }), _jsx(CodeBlock, { ...figure })] }));
+    // The inline form is the same band with no container and no rhythm of its own, so
+    // a caller can hold a sample inside a panel or a Page section they already draw
+    // without this Block adding a second container inside the first.
+    if (layout === 'inline')
+        return sample;
+    return _jsx(Section, { children: sample });
+}
+export default CodeSample01;

package/dist/blocks/code-sample-01/index.d.ts

@@ -0,0 +1,3 @@
+export { CodeSample01, default } from './code-sample.js';
+export type { CodeSample01Props } from './code-sample.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/blocks/code-sample-01/index.d.ts.map

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

package/dist/blocks/code-sample-01/index.js

@@ -0,0 +1 @@
+export { CodeSample01, default } from './code-sample.js';

package/dist/blocks/community-01/community.d.ts

@@ -0,0 +1,183 @@
+import type { LucideIcon } from 'lucide-react';
+import type { ReactNode } from 'react';
+import { type HeadingLevel } from '../../components/ui/section.js';
+/**
+ * One place a product's community is: a channel, a room, a forum, a list.
+ *
+ * `description` is a slot rather than a string on purpose. What a community space
+ * says about itself is the caller's own copy, and in most products it is not one
+ * sentence: it is a topic, or a sentence and a link, or a sentence with a count
+ * the reader cares about in it. A `string` here would make the second of those
+ * three impossible without putting the markup in a string, which is the failure
+ * every `dangerouslySetInnerHTML` prop in this package exists to avoid.
+ */
+export type CommunitySpace = {
+    /** A stable key for the space. */
+    id: string;
+    /** The space's own name, as the space spells it. */
+    name: string;
+    /** What the space is for, in the caller's own words. */
+    description: ReactNode;
+    /**
+     * How many people are in the space. A number and not a sentence, and the
+     * sentence is `membersLabel`. See the Component JSDoc for the whole argument.
+     */
+    members?: number;
+    /** The words for that count, given the number. Required whenever `members` is set. */
+    membersLabel?: (count: number) => string;
+    /**
+     * How many of them are here now. A number and not a sentence, and the sentence
+     * is `onlineLabel`.
+     */
+    online?: number;
+    /** The words for that count, given the number. Required whenever `online` is set. */
+    onlineLabel?: (count: number) => string;
+    /**
+     * Where the space is.
+     *
+     * Required, and required with `hrefLabel` rather than on its own, because a
+     * space with no destination is a description of somewhere the reader cannot get
+     * to. See the Component JSDoc.
+     */
+    href: string;
+    /**
+     * The words on the link, and the sentence that says joining it is a thing you
+     * can do. Required.
+     */
+    hrefLabel: string;
+    /**
+     * The mark beside the name.
+     *
+     * A Lucide component, and the type says so on purpose: Lucide is this system's
+     * icon lane, and the Block draws the tile, the position and the rule around it.
+     * A space whose real identity is an uploaded avatar is application content that
+     * this Block has no slot for, and the answer there is the same one
+     * `Integration01` gives its mark: licensed artwork is the consumer's to supply,
+     * and a set of marks held in a design system is a set of marks that will be
+     * wrong within a year.
+     */
+    icon?: LucideIcon;
+};
+/**
+ * The props a Community01 takes.
+ *
+ * Every string and every number is a prop and the Block ships none. There is no
+ * channel list, no member count, no default sentence for a space and no default
+ * words on the join control, and the absence of the channel list is the sharpest
+ * version of the rule: where a product's community is, and what it is called, is
+ * that product's own fact and it changes with the platform underneath it.
+ */
+export type Community01Props = {
+    /** Optional label above the section title. See the No-Default-Eyebrow Rule. */
+    eyebrow?: string;
+    /** The section title. Required, because a list with no heading is a fragment. */
+    title: ReactNode;
+    /** One or two sentences under the title. */
+    description?: ReactNode;
+    /**
+     * The spaces, in the order a reader should meet them. Order is the caller's
+     * because it is a claim about which one to join first.
+     */
+    spaces: readonly CommunitySpace[];
+    /**
+     * How the spaces are drawn. @defaultValue 'cards'
+     *
+     * `cards` is the default because a space is four things a reader takes
+     * together: what it is called, what it is for, how many people are in it, and
+     * how to get there. `rows` is for a long list or a narrow column, and it puts
+     * the two readings and the link on one line, which is what a list of ten
+     * channels reads like rather than a grid of ten.
+     */
+    variant?: 'cards' | 'rows';
+    /**
+     * What the Block renders in place of the list when there are no spaces.
+     *
+     * A slot rather than a string, and the reason is the same as everywhere else in
+     * this package: the honest sentence is the consumer's, and "there is nowhere to
+     * ask yet" and "nobody has joined" are not variants of one another. Omit it and
+     * a list with no spaces renders nothing at all.
+     */
+    empty?: ReactNode;
+    /**
+     * Heading level for the section title. @defaultValue 'h2'
+     *
+     * See `HeadingLevel`.
+     */
+    headingLevel?: HeadingLevel;
+    /**
+     * Layout only, exactly as on every Block. Changing a Prism-owned visual
+     * property from here is prohibited.
+     */
+    className?: string;
+};
+/**
+ * Where a product's community is: a set of channels or spaces, each with a name, a
+ * description, a member or activity reading, and a way in.
+ *
+ * **This is the NaniSoft reading of a community section, and the translation is
+ * worth stating because the upstream pattern is a list of avatars and this is not
+ * that.** A pipeline that runs has an on-call rotation, a market that is captured
+ * has a watchlist, and an estate that is observed has an operators channel. Those
+ * three are the same object: a named place, a sentence about what belongs in it,
+ * a reading of how many people are in it right now, and a link that gets you
+ * there. What the upstream pattern adds is a wall of member faces, and a wall of
+ * faces is a claim about who a product's users are, drawn from an avatar a
+ * consumer uploaded, in a component that has no way to know whether those faces
+ * consented to being on a marketing page. So the faces are not here, the names
+ * and the readings and the link are, and a consumer who wants faces next to a
+ * space composes them into `description`, which is a slot for exactly that reason.
+ *
+ * **The counts are numbers and the labels are functions, and the Block throws
+ * without them.** "1,204 members" and "204 online" are sentences, the Block cannot
+ * know which, and the reason it cannot know is that they are not two formats of
+ * one fact. A member count is a total and an online count is a moment, and a
+ * reader who has just been shown the second has no way to guess which of the two
+ * a bare figure is when it appears without a word. Every language words them
+ * differently too, including the ones that put the count after the noun and the
+ * ones that inflect it, so a default here would be an English sentence in every
+ * consumer's product with no prop to change it. And a bare numeral beside a
+ * channel name tells a screen reader nothing at all about what it counts: "204
+ * support" is a support queue with two hundred and four items in it to a reader
+ * who cannot see the context, and a number without a noun is a number.
+ *
+ * **`href` requires `hrefLabel`, and the reason is that a space name is a name.**
+ * The sentence that says joining a space is a thing you can do is the caller's,
+ * because "Join", "Open", "Read the channel", "Introduce yourself" and "Get help"
+ * are five different offers and the one that is right depends on what the space
+ * is for and on whether the reader has to fill in a form first. A Block that
+ * wrote one of them would be writing an offer on the consumer's behalf, in
+ * English, in every deployment. So the Block throws rather than shipping a link
+ * whose label is its own, and a caller who has a channel with no join action at
+ * all is describing something that is not a place a reader can go, which is a
+ * different component.
+ *
+ * **The link is a `CtaLink` at the foot of the card, not a link on the whole
+ * card.** A whole card as an anchor is the arrangement `ProductGrid01` uses and it
+ * is right there, because a product row is one destination and the whole row is it.
+ * A community space is a description with a destination attached, and making the
+ * description part of the link's accessible name would hand a screen reader a
+ * sentence ending in a destination for a card whose only actionable part is a
+ * control at the bottom. It would also put a heading inside an anchor, which is
+ * the arrangement that makes "jump to heading" land on something the reader then
+ * has to activate.
+ *
+ * **The space names are headings, and the level is derived rather than written.**
+ * A community list is a set of independent named things a reader may want to jump
+ * to, and a reader navigating by heading is looking for exactly the one they
+ * want. So each name is a heading at `childLevel(headingLevel)`, which means a
+ * Block embedded one level deeper carries its names with it rather than putting
+ * eight `h3`s under an `h3`.
+ *
+ * **The variants are one set of data and two arrangements.** The same space
+ * produces the same name, the same description, the same two readings and the same
+ * link in either form, and only the frame changes, so a consumer who switches
+ * `variant` at render time gets one list in the accessibility tree rather than
+ * two.
+ *
+ * It is a server Component: no hook, no state, no client code and no router. The
+ * join link is a native anchor, so the destination is real and the whole section
+ * costs a consumer nothing in client JavaScript.
+ */
+export declare function Community01({ eyebrow, title, description, spaces, variant, empty, headingLevel, className, }: Community01Props): import("react").JSX.Element | null;
+export default Community01;
+//# sourceMappingURL=community.d.ts.map

package/dist/blocks/community-01/community.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"community.d.ts","sourceRoot":"","sources":["../../../src/blocks/community-01/community.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAC9C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAItC,OAAO,EAAuC,KAAK,YAAY,EAAE,MAAM,6BAA6B,CAAA;AAGpG;;;;;;;;;GASG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,kCAAkC;IAClC,EAAE,EAAE,MAAM,CAAA;IACV,oDAAoD;IACpD,IAAI,EAAE,MAAM,CAAA;IACZ,wDAAwD;IACxD,WAAW,EAAE,SAAS,CAAA;IACtB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,sFAAsF;IACtF,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAA;IACxC;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,qFAAqF;IACrF,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAA;IACvC;;;;;;OAMG;IACH,IAAI,EAAE,MAAM,CAAA;IACZ;;;OAGG;IACH,SAAS,EAAE,MAAM,CAAA;IACjB;;;;;;;;;;OAUG;IACH,IAAI,CAAC,EAAE,UAAU,CAAA;CAClB,CAAA;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,+EAA+E;IAC/E,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,iFAAiF;IACjF,KAAK,EAAE,SAAS,CAAA;IAChB,4CAA4C;IAC5C,WAAW,CAAC,EAAE,SAAS,CAAA;IACvB;;;OAGG;IACH,MAAM,EAAE,SAAS,cAAc,EAAE,CAAA;IACjC;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,OAAO,GAAG,MAAM,CAAA;IAC1B;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,SAAS,CAAA;IACjB;;;;OAIG;IACH,YAAY,CAAC,EAAE,YAAY,CAAA;IAC3B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmEG;AACH,wBAAgB,WAAW,CAAC,EAC1B,OAAO,EACP,KAAK,EACL,WAAW,EACX,MAAM,EACN,OAAiB,EACjB,KAAK,EACL,YAAmB,EACnB,SAAS,GACV,EAAE,gBAAgB,sCAoJlB;AAED,eAAe,WAAW,CAAA"}

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

@@ -0,0 +1,102 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Card, CardContent, CardFooter, CardHeader } from '../../components/ui/card.js';
+import { CtaLink } from '../../components/ui/cta-link.js';
+import { Section, SectionHeading, childLevel } from '../../components/ui/section.js';
+import { cn } from '../../lib/utils.js';
+/**
+ * Where a product's community is: a set of channels or spaces, each with a name, a
+ * description, a member or activity reading, and a way in.
+ *
+ * **This is the NaniSoft reading of a community section, and the translation is
+ * worth stating because the upstream pattern is a list of avatars and this is not
+ * that.** A pipeline that runs has an on-call rotation, a market that is captured
+ * has a watchlist, and an estate that is observed has an operators channel. Those
+ * three are the same object: a named place, a sentence about what belongs in it,
+ * a reading of how many people are in it right now, and a link that gets you
+ * there. What the upstream pattern adds is a wall of member faces, and a wall of
+ * faces is a claim about who a product's users are, drawn from an avatar a
+ * consumer uploaded, in a component that has no way to know whether those faces
+ * consented to being on a marketing page. So the faces are not here, the names
+ * and the readings and the link are, and a consumer who wants faces next to a
+ * space composes them into `description`, which is a slot for exactly that reason.
+ *
+ * **The counts are numbers and the labels are functions, and the Block throws
+ * without them.** "1,204 members" and "204 online" are sentences, the Block cannot
+ * know which, and the reason it cannot know is that they are not two formats of
+ * one fact. A member count is a total and an online count is a moment, and a
+ * reader who has just been shown the second has no way to guess which of the two
+ * a bare figure is when it appears without a word. Every language words them
+ * differently too, including the ones that put the count after the noun and the
+ * ones that inflect it, so a default here would be an English sentence in every
+ * consumer's product with no prop to change it. And a bare numeral beside a
+ * channel name tells a screen reader nothing at all about what it counts: "204
+ * support" is a support queue with two hundred and four items in it to a reader
+ * who cannot see the context, and a number without a noun is a number.
+ *
+ * **`href` requires `hrefLabel`, and the reason is that a space name is a name.**
+ * The sentence that says joining a space is a thing you can do is the caller's,
+ * because "Join", "Open", "Read the channel", "Introduce yourself" and "Get help"
+ * are five different offers and the one that is right depends on what the space
+ * is for and on whether the reader has to fill in a form first. A Block that
+ * wrote one of them would be writing an offer on the consumer's behalf, in
+ * English, in every deployment. So the Block throws rather than shipping a link
+ * whose label is its own, and a caller who has a channel with no join action at
+ * all is describing something that is not a place a reader can go, which is a
+ * different component.
+ *
+ * **The link is a `CtaLink` at the foot of the card, not a link on the whole
+ * card.** A whole card as an anchor is the arrangement `ProductGrid01` uses and it
+ * is right there, because a product row is one destination and the whole row is it.
+ * A community space is a description with a destination attached, and making the
+ * description part of the link's accessible name would hand a screen reader a
+ * sentence ending in a destination for a card whose only actionable part is a
+ * control at the bottom. It would also put a heading inside an anchor, which is
+ * the arrangement that makes "jump to heading" land on something the reader then
+ * has to activate.
+ *
+ * **The space names are headings, and the level is derived rather than written.**
+ * A community list is a set of independent named things a reader may want to jump
+ * to, and a reader navigating by heading is looking for exactly the one they
+ * want. So each name is a heading at `childLevel(headingLevel)`, which means a
+ * Block embedded one level deeper carries its names with it rather than putting
+ * eight `h3`s under an `h3`.
+ *
+ * **The variants are one set of data and two arrangements.** The same space
+ * produces the same name, the same description, the same two readings and the same
+ * link in either form, and only the frame changes, so a consumer who switches
+ * `variant` at render time gets one list in the accessibility tree rather than
+ * two.
+ *
+ * It is a server Component: no hook, no state, no client code and no router. The
+ * join link is a native anchor, so the destination is real and the whole section
+ * costs a consumer nothing in client JavaScript.
+ */
+export function Community01({ eyebrow, title, description, spaces, variant = 'cards', empty, headingLevel = 'h2', className, }) {
+    for (const space of spaces) {
+        if (!space.hrefLabel) {
+            throw new Error('Community01: a space carries an href with no hrefLabel, so the control that gets a reader into ' +
+                'it would be a link announced by its destination alone. A space name is a name, and the ' +
+                'sentence saying that joining the space is a thing you can do belongs to the caller.');
+        }
+        if (space.members !== undefined && !space.membersLabel) {
+            throw new Error('Community01: a space carries a member count with no membersLabel, so the reading would be a bare ' +
+                'numeral beside a channel name, which tells a screen reader nothing about what it counts. Pass ' +
+                'the words for the count in your own language.');
+        }
+        if (space.online !== undefined && !space.onlineLabel) {
+            throw new Error('Community01: a space carries an online count with no onlineLabel, so the reading would be a bare ' +
+                'numeral beside a channel name, and a reader could not tell a moment from a total. Pass the ' +
+                'words for the count in your own language.');
+        }
+    }
+    if (spaces.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": "community-empty", className: "text-muted-foreground text-pretty text-sm", children: empty })] }));
+    }
+    // One step below the section, and not a literal, so the names follow the
+    // section when the Block is composed one level deeper than it was written for.
+    const Title = childLevel(headingLevel);
+    return (_jsxs(Section, { children: [_jsx(SectionHeading, { as: headingLevel, align: "left", eyebrow: eyebrow, title: title, description: description, className: "mb-10" }), variant === 'cards' ? (_jsx("ul", { "data-slot": "community-cards", className: cn('grid gap-6 sm:grid-cols-2 lg:grid-cols-3', className), children: spaces.map((space) => (_jsx("li", { "data-slot": "community-card", className: "flex", children: _jsxs(Card, { className: "w-full gap-4", children: [_jsxs(CardHeader, { className: "gap-3", children: [_jsx("span", { "aria-hidden": true, "data-slot": "community-icon", className: "border-border bg-muted text-muted-foreground flex size-9 shrink-0 items-center justify-center rounded-lg border", children: space.icon === undefined ? null : _jsx(space.icon, { className: "size-4" }) }), _jsx(Title, { "data-slot": "community-name", className: "text-base", children: space.name })] }), _jsx(CardContent, { className: "text-muted-foreground text-pretty text-sm", children: space.description }), space.members === undefined && space.online === undefined ? null : (_jsxs("div", { "data-slot": "community-readings", className: "text-muted-foreground flex flex-wrap items-center gap-x-4 gap-y-1 text-xs", children: [space.members === undefined ? null : (_jsx("span", { "data-slot": "community-members", children: space.membersLabel?.(space.members) })), space.online === undefined ? null : (_jsx("span", { "data-slot": "community-online", children: space.onlineLabel?.(space.online) }))] })), _jsx(CardFooter, { children: _jsx(CtaLink, { href: space.href, size: "sm", variant: "outline", children: space.hrefLabel }) })] }) }, space.id))) })) : (_jsx("ul", { "data-slot": "community-rows", className: cn('flex flex-col', className), children: spaces.map((space) => (_jsxs("li", { "data-slot": "community-row", className: "border-border flex flex-wrap items-center gap-x-6 gap-y-2 border-b py-4 first:border-t", children: [_jsx("span", { "aria-hidden": true, "data-slot": "community-icon", className: "border-border bg-muted text-muted-foreground flex size-8 shrink-0 items-center justify-center rounded-lg border", children: space.icon === undefined ? null : _jsx(space.icon, { className: "size-4" }) }), _jsx(Title, { "data-slot": "community-name", className: "text-sm", children: space.name }), _jsx("span", { "data-slot": "community-description", className: "text-muted-foreground min-w-0 flex-1 text-pretty text-sm", children: space.description }), space.members === undefined ? null : (_jsx("span", { "data-slot": "community-members", className: "text-muted-foreground text-xs", children: space.membersLabel?.(space.members) })), space.online === undefined ? null : (_jsx("span", { "data-slot": "community-online", className: "text-muted-foreground text-xs", children: space.onlineLabel?.(space.online) })), _jsx(CtaLink, { href: space.href, size: "sm", variant: "ghost", children: space.hrefLabel })] }, space.id))) }))] }));
+}
+export default Community01;

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

@@ -0,0 +1,3 @@
+export { Community01, default } from './community.js';
+export type { Community01Props, CommunitySpace } from './community.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/blocks/community-01/index.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,aAAa,CAAA;AAKlD,YAAY,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA"}

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

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