@nebutra/ui 0.2.2 → 2.0.0

package/dist/editorial/index.d.ts

@@ -0,0 +1,404 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode, CSSProperties } from 'react';
+import * as class_variance_authority_types from 'class-variance-authority/types';
+
+type EditorialAuthorLink = {
+    href: string;
+    key?: string;
+    label: string;
+};
+type EditorialAuthorBioProps = {
+    /** Avatar slot. Apps pass their own image component so this stays framework-free. */
+    avatar?: ReactNode;
+    bio?: string | null;
+    className?: string;
+    label?: string;
+    links?: EditorialAuthorLink[];
+    name: string;
+    role?: string | null;
+};
+/** Byline card closing an article. */
+declare function EditorialAuthorBio({ avatar, bio, className, label, links, name, role, }: EditorialAuthorBioProps): react_jsx_runtime.JSX.Element | null;
+
+/**
+ * Shared visual grammar for long-form editorial blocks.
+ *
+ * Every block in this directory composes these recipes instead of hand-picking
+ * borders, radii and shadows, so a change to the editorial voice is one edit
+ * here rather than fifteen edits across the renderer.
+ *
+ * The grammar is hairline-first: separation comes from a 1px border plus the
+ * ambient elevation ramp, never from a filled colour panel. Tone is carried by
+ * a 2px rail and an icon, so a page of stacked blocks still reads as one
+ * document rather than a row of coloured cards.
+ */
+/** Uppercase micro-label that opens a block. Not part of the registered type scale. */
+declare const EDITORIAL_EYEBROW = "text-[0.6875rem] font-semibold uppercase leading-none tracking-[0.14em] text-muted-foreground";
+/** Caption / footnote text under a figure, table or chart. */
+declare const EDITORIAL_CAPTION = "text-sm leading-6 text-muted-foreground";
+/** Body copy inside a block. One step tighter than article prose. */
+declare const EDITORIAL_BODY = "text-[0.9375rem] leading-7 text-muted-foreground";
+/** Block title. Sits below an article h3 so it never competes with the outline. */
+declare const EDITORIAL_TITLE = "text-base font-semibold leading-6 text-foreground";
+/**
+ * Figures are numeric, so they take tabular lining figures — otherwise a column
+ * of stats visually ragged-rights itself as digit widths change.
+ */
+declare const EDITORIAL_FIGURE = "font-mono font-semibold tabular-nums text-foreground";
+/**
+ * Article body is a ~3xl reading column. Blocks that carry a grid, a table or a
+ * chart earn width by breaking out of it; prose-adjacent blocks stay inline so
+ * the measure is preserved.
+ */
+declare const editorialBlock: (props?: ({
+    width?: "column" | "breakout" | "full" | null | undefined;
+    spacing?: "none" | "tight" | "normal" | "loose" | null | undefined;
+} & class_variance_authority_types.ClassProp) | undefined) => string;
+/**
+ * Surface recipe. `resting` is the default for a card in flow; `raised` is for
+ * the one block in a set that should read as emphasised, not for every card.
+ */
+declare const editorialFrame: (props?: ({
+    radius?: "card" | "panel" | "inner" | null | undefined;
+    elevation?: "flat" | "resting" | "raised" | null | undefined;
+} & class_variance_authority_types.ClassProp) | undefined) => string;
+declare const EDITORIAL_TONES: readonly ["note", "insight", "success", "warning", "danger"];
+type EditorialTone = (typeof EDITORIAL_TONES)[number];
+declare function editorialToneAccent(tone: EditorialTone): string;
+declare function isEditorialTone(value: unknown): value is EditorialTone;
+/**
+ * Inline custom property consumed by the tone-aware utility classes below.
+ * `--editorial-tone` is a private name: shadowing a core token such as
+ * `--primary` on an element would leak into the whole subtree.
+ */
+declare function editorialToneStyle(tone: EditorialTone): CSSProperties;
+/** Foreground for icons and rails. */
+declare const EDITORIAL_TONE_FG = "text-[color:var(--editorial-tone)]";
+/** 5% wash — enough to register as tinted, not enough to read as a coloured block. */
+declare const EDITORIAL_TONE_WASH = "bg-[color-mix(in_srgb,var(--editorial-tone)_5%,transparent)]";
+/** 12% plate behind an icon. */
+declare const EDITORIAL_TONE_PLATE = "bg-[color-mix(in_srgb,var(--editorial-tone)_12%,transparent)]";
+
+type EditorialCalloutProps = {
+    /** Body copy. A string is wrapped in a paragraph; nodes are rendered as given. */
+    children?: ReactNode;
+    className?: string;
+    /** Shown in the eyebrow slot when there is no title — pass a localized word. */
+    label?: string;
+    title?: string | null;
+    tone?: EditorialTone;
+};
+/**
+ * Aside for a note, insight, caution or correction.
+ *
+ * Tone is a 2px rail plus a tinted icon plate, not a filled panel: a reader
+ * scrolling past four callouts should see four asides, not four highlighter
+ * swipes.
+ */
+declare function EditorialCallout({ children, className, label, title, tone, }: EditorialCalloutProps): react_jsx_runtime.JSX.Element | null;
+
+type EditorialChartPoint = {
+    /** Optional per-point display string. Falls back to the raw value. */
+    display?: string | null;
+    key?: string;
+    label: string;
+    value: number;
+};
+type EditorialChartProps = {
+    caption?: string | null;
+    className?: string;
+    label?: string;
+    points: EditorialChartPoint[];
+    title?: string | null;
+    variant?: "bar" | "line";
+};
+/**
+ * Small inline data figure.
+ *
+ * Values are also emitted as a visually hidden table, so the chart is readable
+ * without sight of the bars and copyable as data rather than as an image.
+ */
+declare function EditorialChart({ caption, className, label, points, title, variant, }: EditorialChartProps): react_jsx_runtime.JSX.Element | null;
+
+type EditorialComparisonRow = {
+    cells: string[];
+    key?: string;
+    label: string;
+};
+type EditorialComparisonTableProps = {
+    className?: string;
+    columns: string[];
+    /**
+     * Header for the row-label column. Localize it — leaving this to a hardcoded
+     * English default is how "Dimension" ended up in Chinese articles.
+     */
+    dimensionLabel?: string;
+    label?: string;
+    rows: EditorialComparisonRow[];
+    title?: string | null;
+};
+/**
+ * Matrix comparing options across dimensions.
+ *
+ * Below `md` the table restacks into one block per row and each cell carries
+ * its own column label, so the reader never has to drag a table sideways on a
+ * phone to find out which column a value belonged to.
+ */
+declare function EditorialComparisonTable({ className, columns, dimensionLabel, label, rows, title, }: EditorialComparisonTableProps): react_jsx_runtime.JSX.Element | null;
+
+type EditorialDataTableRow = {
+    cells: ReactNode[];
+    key: string;
+};
+type EditorialDataTableProps = {
+    caption?: ReactNode;
+    className?: string;
+    head: ReactNode[];
+    rows: EditorialDataTableRow[];
+};
+/**
+ * Table rendered from author-written markup, where cells carry links, code and
+ * inline math rather than plain strings.
+ *
+ * Cells are `ReactNode`, so unlike `EditorialComparisonTable` this cannot
+ * restack into labelled blocks on small screens — it scrolls instead, inside a
+ * framed container that makes the clipped edge obvious.
+ */
+declare function EditorialDataTable({ caption, className, head, rows }: EditorialDataTableProps): react_jsx_runtime.JSX.Element | null;
+
+type EditorialDividerProps = {
+    className?: string;
+};
+/**
+ * Section break inside an article.
+ *
+ * Marks a change of movement, not a new heading — an `<hr>` with a centred
+ * marker rather than a rule that would read as the end of the piece.
+ */
+declare function EditorialDivider({ className }: EditorialDividerProps): react_jsx_runtime.JSX.Element;
+
+declare const EDITORIAL_EMBED_PROVIDERS: readonly ["youtube", "x", "github", "website"];
+type EditorialEmbedProvider = (typeof EDITORIAL_EMBED_PROVIDERS)[number];
+type EditorialEmbedCardProps = {
+    caption?: string | null;
+    className?: string;
+    provider?: EditorialEmbedProvider;
+    title: string;
+    url: string;
+};
+declare function isEditorialEmbedProvider(value: unknown): value is EditorialEmbedProvider;
+/**
+ * Link-out card for third-party media.
+ *
+ * Deliberately not an iframe: an embedded player ships the provider's scripts
+ * and cookies into the article and moves the layout around while it loads. The
+ * card states the provider, keeps the destination visible, and leaves the
+ * decision to the reader.
+ */
+declare function EditorialEmbedCard({ caption, className, provider, title, url, }: EditorialEmbedCardProps): react_jsx_runtime.JSX.Element | null;
+
+type EditorialEntityChipProps = {
+    className?: string;
+    href?: string | null;
+    /** Logo slot. Apps pass their own image component so this stays framework-free. */
+    logo?: ReactNode;
+    name: string;
+};
+/**
+ * Inline reference to a company, product or project.
+ *
+ * Sized to sit inside a sentence without changing its line height, which is
+ * why the logo plate is `1em` rather than a fixed pixel size.
+ */
+declare function EditorialEntityChip({ className, href, logo, name }: EditorialEntityChipProps): react_jsx_runtime.JSX.Element | null;
+
+type EditorialFaqItem = {
+    answer: string;
+    key?: string;
+    question: string;
+};
+type EditorialFaqProps = {
+    className?: string;
+    /** Open the first entry on load, for a short list where the answer is the point. */
+    defaultOpenFirst?: boolean;
+    items: EditorialFaqItem[];
+    label?: string;
+    title?: string | null;
+};
+/**
+ * Collapsible question list.
+ *
+ * Built on native `<details>` rather than a JS disclosure: it costs no client
+ * bundle, works before hydration, is keyboard-operable for free, and lets
+ * in-page find surface answers inside collapsed entries.
+ */
+declare function EditorialFaq({ className, defaultOpenFirst, items, label, title, }: EditorialFaqProps): react_jsx_runtime.JSX.Element | null;
+
+type EditorialFigureProps = {
+    caption?: ReactNode;
+    className?: string;
+    /**
+     * Image slot. Apps pass their own image component — keeping `next/image` out
+     * of this package is what lets it render in Storybook and non-Next surfaces.
+     */
+    media: ReactNode;
+    width?: "column" | "breakout" | "full";
+};
+/** Single image with an optional caption. */
+declare function EditorialFigure({ caption, className, media, width, }: EditorialFigureProps): react_jsx_runtime.JSX.Element;
+type EditorialFigureGroupProps = {
+    className?: string;
+    /** Rendered figures. Two or three read best; more should become a gallery. */
+    children: ReactNode;
+    label?: string;
+    title?: string | null;
+    variant?: "grid" | "comparison" | "sequence";
+};
+/** Set of related figures shown together. */
+declare function EditorialFigureGroup({ children, className, label, title, variant, }: EditorialFigureGroupProps): react_jsx_runtime.JSX.Element;
+
+type EditorialKeyTakeawayItem = {
+    key?: string;
+    text: string;
+};
+type EditorialKeyTakeawaysProps = {
+    className?: string;
+    items: EditorialKeyTakeawayItem[];
+    /** Eyebrow copy. Pass a localized string; the default is English. */
+    label?: string;
+    title?: string | null;
+};
+/**
+ * The summary panel that opens a long piece.
+ *
+ * Numbering is a hairline-separated ordered list rather than bullets or cards —
+ * the point is that a reader can take four lines and leave, so nothing should
+ * compete with the lines themselves.
+ */
+declare function EditorialKeyTakeaways({ className, items, label, title, }: EditorialKeyTakeawaysProps): react_jsx_runtime.JSX.Element | null;
+
+type EditorialMarginNoteProps = {
+    children?: string | null;
+    className?: string;
+    label?: string;
+    title?: string | null;
+};
+/**
+ * Short aside that steps out into the right margin on wide screens.
+ *
+ * Below `xl` there is no margin to step into, so it degrades to an indented
+ * inline note rather than a floated box that would strand a two-word orphan
+ * beside it.
+ */
+declare function EditorialMarginNote({ children, className, label, title, }: EditorialMarginNoteProps): react_jsx_runtime.JSX.Element | null;
+
+type EditorialPullQuoteProps = {
+    /** Name of the speaker or the work being quoted. */
+    attribution?: string | null;
+    className?: string;
+    /** Portrait slot. Apps pass their own image component so this stays framework-free. */
+    portrait?: ReactNode;
+    quote: string;
+    /** Title, company or context under the attribution. */
+    role?: string | null;
+    sourceHref?: string | null;
+};
+/**
+ * Display quote lifted out of the reading column.
+ *
+ * There is no oversized quotation glyph: at this size the type itself already
+ * reads as a quote, and the glyph only competes with the first word. Hairlines
+ * above and below do the separating.
+ */
+declare function EditorialPullQuote({ attribution, className, portrait, quote, role, sourceHref, }: EditorialPullQuoteProps): react_jsx_runtime.JSX.Element | null;
+
+type EditorialSourceItem = {
+    accessedAt?: string | null;
+    author?: string | null;
+    key?: string;
+    publisher?: string | null;
+    summary?: string | null;
+    title: string;
+    url: string;
+};
+type EditorialSourceIndexProps = {
+    className?: string;
+    /** Eyebrow copy, e.g. "Source index" / "资料索引". */
+    label?: string;
+    sources: EditorialSourceItem[];
+    /** Sentence under the eyebrow. Apps build this so pluralization stays localized. */
+    summary?: string | null;
+};
+/**
+ * Numbered reference list closing a researched piece.
+ *
+ * A numbered hairline list rather than a card grid: references are read in
+ * order and cited by number from the body, and boxing each one hides that
+ * ordering behind a wall of equal-weight rectangles.
+ */
+declare function EditorialSourceIndex({ className, label, sources, summary, }: EditorialSourceIndexProps): react_jsx_runtime.JSX.Element | null;
+
+type EditorialStatItem = {
+    caption?: string | null;
+    key?: string;
+    label: string;
+    value: string;
+};
+type EditorialStatGridProps = {
+    className?: string;
+    items: EditorialStatItem[];
+    label?: string;
+    title?: string | null;
+};
+/**
+ * Row of headline figures.
+ *
+ * Cells are separated by shared hairlines rather than being individual cards:
+ * boxing each number makes the set read as four unrelated facts, where the
+ * point of a stat row is that they are one measurement taken four ways.
+ */
+declare function EditorialStatGrid({ className, items, label, title }: EditorialStatGridProps): react_jsx_runtime.JSX.Element | null;
+
+type EditorialStep = {
+    body?: string | null;
+    key?: string;
+    title: string;
+};
+type EditorialStepLadderProps = {
+    className?: string;
+    label?: string;
+    steps: EditorialStep[];
+    title?: string | null;
+};
+/**
+ * Ordered procedure.
+ *
+ * Distinct from `EditorialTimeline`: a timeline reports what happened and is
+ * marked with dates, a ladder instructs and is marked with positions the reader
+ * is meant to follow in order.
+ */
+declare function EditorialStepLadder({ className, label, steps, title }: EditorialStepLadderProps): react_jsx_runtime.JSX.Element | null;
+
+type EditorialTimelineItem = {
+    body?: string | null;
+    /** Short marker: a year, a quarter, a version. Rendered in tabular figures. */
+    marker: string;
+    key?: string;
+    title: string;
+};
+type EditorialTimelineProps = {
+    className?: string;
+    items: EditorialTimelineItem[];
+    label?: string;
+    title?: string | null;
+};
+/**
+ * Chronology of events along a single rail.
+ *
+ * The rail is a 1px border on the list rather than a drawn line per item, so
+ * it stays continuous between entries and collapses cleanly when an entry has
+ * no body.
+ */
+declare function EditorialTimeline({ className, items, label, title }: EditorialTimelineProps): react_jsx_runtime.JSX.Element | null;
+
+export { EDITORIAL_BODY, EDITORIAL_CAPTION, EDITORIAL_EMBED_PROVIDERS, EDITORIAL_EYEBROW, EDITORIAL_FIGURE, EDITORIAL_TITLE, EDITORIAL_TONES, EDITORIAL_TONE_FG, EDITORIAL_TONE_PLATE, EDITORIAL_TONE_WASH, EditorialAuthorBio, type EditorialAuthorBioProps, type EditorialAuthorLink, EditorialCallout, type EditorialCalloutProps, EditorialChart, type EditorialChartPoint, type EditorialChartProps, type EditorialComparisonRow, EditorialComparisonTable, type EditorialComparisonTableProps, EditorialDataTable, type EditorialDataTableProps, type EditorialDataTableRow, EditorialDivider, type EditorialDividerProps, EditorialEmbedCard, type EditorialEmbedCardProps, type EditorialEmbedProvider, EditorialEntityChip, type EditorialEntityChipProps, EditorialFaq, type EditorialFaqItem, type EditorialFaqProps, EditorialFigure, EditorialFigureGroup, type EditorialFigureGroupProps, type EditorialFigureProps, type EditorialKeyTakeawayItem, EditorialKeyTakeaways, type EditorialKeyTakeawaysProps, EditorialMarginNote, type EditorialMarginNoteProps, EditorialPullQuote, type EditorialPullQuoteProps, EditorialSourceIndex, type EditorialSourceIndexProps, type EditorialSourceItem, EditorialStatGrid, type EditorialStatGridProps, type EditorialStatItem, type EditorialStep, EditorialStepLadder, type EditorialStepLadderProps, EditorialTimeline, type EditorialTimelineItem, type EditorialTimelineProps, type EditorialTone, editorialBlock, editorialFrame, editorialToneAccent, editorialToneStyle, isEditorialEmbedProvider, isEditorialTone };