@misoto22/design 0.5.0 → 0.6.0

package/dist/agent/index.md

@@ -0,0 +1,131 @@
+# @misoto22/design 0.6.0
+
+> Monochrome design system: portable CSS tokens and accessible React 19
+> primitives. Components ship compiled — import them, do not copy them.
+
+Install: `npm install @misoto22/design`. Styles: `import '@misoto22/design/styles.css'`.
+
+One component, in full, offline:
+
+```bash
+npx misoto22-design docs <Component>
+```
+
+## Theme axes
+
+Attributes, independent, and they work on any element — not just the root.
+An unset axis is the default.
+
+- `data-chart-palette`: `chroma` (unset = the neutral series ramp)
+- `data-density`: `compact` (unset = comfortable)
+- `data-mode`: `dark` `light` (unset = follows the app)
+- `data-motion`: `snappy` `still` (unset = calm)
+- `data-radius`: `round` `sharp` (unset = the default radius ladder)
+- `data-rules`: `firm` `quiet` (unset = hairline)
+- `data-surface`: `cool` `glass` `warm` (unset = paper)
+- `data-table-density`: `compact` (unset = comfortable — whatever `data-density` is doing around it)
+- `data-type`: `bookish` `grotesk` (unset = editorial)
+
+There is no `data-accent` attribute: `--accent` is a CSS custom property,
+re-pointed in a stylesheet.
+
+## Components
+
+### Actions
+
+- **Button** — The system’s action, on the same corner as the field beside it.
+- **FloatingIconButton** — A round action pinned to a screen corner.
+
+### Forms
+
+- **Field** — A labelled form row: label, control, and the one message below it.
+- **Input** — A single line of text entry.
+- **Textarea** — Multi-line text entry, resizable vertically only.
+- **Select** — A choice from a list, styled the whole way down.
+- **NativeSelect** — The platform’s own picker, restyled where it can be.
+- **Checkbox** — A choice that takes effect when the form is submitted.
+- **RadioGroup** — A set of mutually exclusive choices.
+- **Switch** — A setting that takes effect immediately.
+- **Combobox** — A select you can type into.
+- **DatePicker** — A date — or a span of them — chosen from a calendar.
+- **Slider** — A value chosen along a range.
+- **ToggleGroup** — A segmented control: several options, one strip.
+
+### Navigation
+
+- **Tabs** — One strip, several panels.
+- **Accordion** — Disclosure rows that open in place.
+- **Breadcrumb** — Where you are, as a path.
+- **Pagination** — Numbered pages, with the middle elided.
+- **NavItem** — A row in a sidebar.
+- **Collapsible** — One thing that opens, on its own.
+
+### Overlays
+
+- **Dialog** — A modal surface: portal, scrim, centred panel.
+- **DropdownMenu** — A menu of actions.
+- **Tooltip** — A short label on hover and on focus.
+- **Popover** — A panel anchored to a control, holding content you can interact with.
+- **Sheet** — A panel docked to an edge of the viewport.
+- **ContextMenu** — The menu a right-click opens.
+- **SearchableMenu** — A menu of actions you can type into.
+- **Command** — A filterable list of actions — the ⌘K surface.
+
+### Feedback
+
+- **Spinner** — The one “working” indicator — a ring, never a shimmer.
+- **Skeleton** — The shape of the page, before the page.
+- **Progress** — A bar that fills, or sweeps when the end is unknown.
+- **Alert** — A message about the page, in place.
+- **EmptyState** — A collection with nothing in it — yet.
+- **ErrorState** — A page that could not be shown.
+- **Toast** — A transient confirmation, mounted once near the app root.
+
+### Display
+
+- **Badge** — A count or a state, set in mono so it reads as metadata.
+- **Tag** — A subject label — a topic, a technology, a filter facet.
+- **Kbd** — A key on a keyboard, set as one.
+- **Avatar** — A person, as a circle, with initials until the image lands.
+- **StatusDot** — The dot beside a status word.
+- **Steps** — A numbered sequence, as a rail — one thing after another, with a rule through them.
+- **StatusPill** — A live state, named: a dot plus an uppercase mono label.
+- **LinkArrow** — The mark on a link that leaves the page.
+- **Separator** — A rule, in the three weights a monochrome page needs.
+- **Diagram** — A flow or architecture figure, drawn out of the system’s own parts.
+- **FigureBand** — A row of counted facts, divided by hairlines and nothing else.
+
+### Surfaces
+
+- **Article** — The long-form reading surface — everything a Markdown pipeline emits, in this system’s type.
+- **Card** — A bounded surface, with no shadow under it.
+- **AppShell** — Two columns on a desktop, a drawer on a phone.
+- **Calendar** — A month, as a grid of days.
+- **ScrollArea** — A box that scrolls, with a scrollbar that looks the same everywhere.
+
+### Data
+
+- **Table** — A ruled data table — alignment, sorting and rules all per column.
+- **Heatmap** — A grid of values read by weight.
+- **Sparkline** — A run of numbers at the size of a word.
+- **BarList** — A ranked list, with the bar behind the name rather than beside it.
+- **BigNumber** — One number, at the size of a headline.
+- **BulletChart** — A measure, its target, and the bands that say whether it is any good.
+
+### Charts
+
+- **AreaChart** — A filled series over a continuous axis, where the area means something.
+- **BarChart** — Discrete categories compared by length.
+- **LineChart** — Several series compared over a continuous axis.
+- **ComposedChart** — Bars and lines over one axis — the volume, and the rate it moved at.
+- **PieChart** — Parts of one whole.
+- **RadarChart** — A profile across several named dimensions.
+- **RadialChart** — Values on an arc — a gauge, or a few totals against one scale.
+- **SankeyChart** — Where a quantity goes as it moves through stages.
+- **ScatterChart** — Two measures against each other, one mark per observation.
+- **FunnelChart** — Stages that only ever narrow.
+- **TreemapChart** — Part of a whole, when the whole has too many parts for a pie — and the parts nest.
+- **BoxPlot** — The spread of a measurement, per category.
+- **Histogram** — The shape of one distribution.
+- **WaterfallChart** — How a total got from one figure to another.
+- **Facet** — The same chart once per group, on one shared scale.

package/dist/charts/AreaChart/AreaChart.d.ts

@@ -0,0 +1,191 @@
+import * as react from 'react';
+import { ReactNode, ComponentProps, FC } from 'react';
+import { AreaChart as AreaChart$1, Area, XAxis, YAxis, CartesianGrid } from 'recharts';
+import { ChartConfig } from '../lib/chart.js';
+import { ChartEmptyProps } from '../lib/empty.js';
+import { ValuesProps } from '../lib/values.js';
+import { SonifyProps } from '../lib/sonify-control.js';
+import { ChartBackgroundVariant } from '../lib/background.js';
+import { BrushProps } from '../lib/brush.js';
+import { ToolbarProps } from '../lib/toolbar.js';
+import { ChartRevealType } from '../lib/paint.js';
+import { ChartDotVariant } from '../lib/dot.js';
+import { ChartLegendVariant, ChartLegendAlign } from '../lib/legend.js';
+import { ChartTooltipVariant, ChartTooltipRoundness } from '../lib/tooltip.js';
+import { ReferenceLine, ReferenceBand, Annotation } from '../lib/annotations.js';
+import '../lib/sonify.js';
+import '../lib/zoom.js';
+import '../lib/figure.js';
+import 'recharts/types/component/DefaultTooltipContent';
+
+/**
+ * The axis props, with `label` narrowed to a string.
+ *
+ * Recharts' own `label` accepts a render function and a config object, neither
+ * of which a call site should be reaching for to name an axis — and both of
+ * which would let a consumer opt out of the system's own axis type styling
+ * without noticing.
+ */
+type ChartXAxisProps = Omit<ComponentProps<typeof XAxis>, 'label'> & {
+    /** What this axis measures. Say the unit here or in the series label, once. */
+    label?: string;
+};
+type ChartYAxisProps = Omit<ComponentProps<typeof YAxis>, 'label'> & {
+    /** What this axis measures. Say the unit here or in the series label, once. */
+    label?: string;
+};
+
+/** How an area's curve is interpolated between points. */
+type ChartCurveType = ComponentProps<typeof Area>['type'];
+/**
+ * How an area meets the plot.
+ *
+ * In the monochrome default this is the PRIMARY way two series are told apart
+ * — the ramp is the second encoding — so a chart with more than one area
+ * should vary this before it varies anything else.
+ */
+type AreaVariant = 'gradient' | 'gradient-reverse' | 'solid' | 'dotted' | 'lines' | 'hatched';
+/** How the line on top of an area is drawn. */
+type AreaStrokeVariant = 'solid' | 'dashed' | 'animated-dashed';
+/** How several areas combine: side by side, stacked, or normalised to 100%. */
+type AreaStackType = 'default' | 'stacked' | 'expanded';
+/** Fails the build when a config names a series the rows do not have. */
+type ValidateKeys<TData, TConfig> = {
+    [K in keyof TConfig]: K extends keyof TData ? ChartConfig[string] : never;
+};
+interface AreaChartProps<TData extends Record<string, unknown>, TConfig extends Record<string, ChartConfig[string]>> {
+    /** Series keys → their label and paint. Declaration order is ramp order. */
+    config: TConfig & ValidateKeys<TData, TConfig>;
+    /** The rows the chart draws. One entry per point, bar or category. */
+    data: TData[];
+    /**
+     * What the chart shows, in a sentence a reader could act on. Required, and
+     * announced to a screen reader even when it is not printed.
+     */
+    title: string;
+    /** Prints the title above the plot instead of hiding it from sight. */
+    showTitle?: boolean;
+    /** A line under the title — the unit, the window, the caveat. */
+    description?: ReactNode;
+    /**
+     * The composed parts — axes, grid, tooltip, legend, and the marks
+     * themselves.
+     */
+    children: ReactNode;
+    /** Merged onto the figure, last, so a call site can size or space it. */
+    className?: string;
+    /** Escape hatch onto the raw Recharts chart element. */
+    chartProps?: ComponentProps<typeof AreaChart$1>;
+    /** The curve every `<AreaChart.Area>` inherits. */
+    curveType?: ChartCurveType;
+    /** The intro wipe every `<AreaChart.Area>` inherits. */
+    animationType?: ChartRevealType;
+    /** How several marks combine: side by side, stacked, or normalised to 100%. */
+    stackType?: AreaStackType;
+    /** The series lit on first render. Selection dims every other series. */
+    defaultSelectedDataKey?: string | null;
+    /** Fires when the selection changes, and with null when it is cleared. */
+    onSelectionChange?: (selectedDataKey: string | null) => void;
+    /**
+     * Swaps the marks for an animated skeleton, keeping the measured height so
+     * the page does not jump when the data lands.
+     */
+    isLoading?: boolean;
+    /** How many points the skeleton draws. */
+    loadingPoints?: number;
+    /**
+     * The row field on the category axis. Needed by the brush and by the table
+     * view.
+     */
+    xDataKey?: keyof TData & string;
+    /**
+     * Drops the hidden table view. Only correct when the page prints the data
+     * itself.
+     */
+    hideDataTable?: boolean;
+    /**
+     * What the chart shows when it has nothing to draw.
+     *
+     * Rendered instead of the plot whenever `data` is empty and the chart is not
+     * loading — the state a real dashboard reaches within a week, and the one an
+     * empty pair of axes is indistinguishable from a failed load. `false` keeps
+     * the axes, for a chart whose emptiness is itself the reading.
+     */
+    empty?: ChartEmptyProps | false;
+}
+/**
+ * A filled series over a category axis — the shape for a magnitude that is
+ * continuous, where the area under the line means something.
+ *
+ * Composed rather than configured: axes, grid, tooltip, legend and the areas
+ * themselves are children, so a chart renders exactly the parts it asked for
+ * and nothing is switched on by a prop nobody can see.
+ *
+ * Reach for `<LineChart>` instead when the reader is comparing several series
+ * against each other rather than reading one total, and for `<BarChart>` when
+ * the categories are discrete.
+ *
+ * @example
+ * <AreaChart title="Visitors per month" config={config} data={data} xDataKey="month">
+ *   <AreaChart.Grid />
+ *   <AreaChart.XAxis dataKey="month" />
+ *   <AreaChart.Tooltip />
+ *   <AreaChart.Area dataKey="desktop" variant="gradient" />
+ * </AreaChart>
+ */
+declare function AreaChart<TData extends Record<string, unknown>, TConfig extends Record<string, ChartConfig[string]>>({ config, data, title, showTitle, description, children, className, chartProps, curveType, animationType, stackType, defaultSelectedDataKey, onSelectionChange, isLoading, loadingPoints, xDataKey, hideDataTable, empty, }: AreaChartProps<TData, TConfig>): react.JSX.Element;
+declare namespace AreaChart {
+    var Area: ({ dataKey, variant, strokeVariant, strokeWidth, curveType, animationType, connectNulls, isClickable, children, areaProps, }: AreaProps) => react.JSX.Element | null;
+    var Dot: FC<DotProps>;
+    var ActiveDot: FC<DotProps>;
+    var XAxis: ({ tickLine, axisLine, tickMargin, minTickGap, label, ...rest }: ChartXAxisProps) => react.JSX.Element | null;
+    var YAxis: ({ tickLine, axisLine, tickMargin, minTickGap, width, tickFormatter, label, ...rest }: ChartYAxisProps) => react.JSX.Element | null;
+    var Grid: ({ vertical, strokeDasharray, ...rest }: ComponentProps<typeof CartesianGrid>) => react.JSX.Element;
+    var Tooltip: ({ variant, roundness, defaultIndex, cursor }: ChartTooltipSlotProps) => react.JSX.Element | null;
+    var Legend: ({ variant, align, verticalAlign, isClickable, }: ChartLegendSlotProps) => react.JSX.Element;
+    var Background: ({ variant }: {
+        variant: ChartBackgroundVariant;
+    }) => react.JSX.Element | null;
+    var ReferenceLine: typeof ReferenceLine;
+    var ReferenceBand: typeof ReferenceBand;
+    var Annotation: typeof Annotation;
+    var Values: FC<ValuesProps>;
+    var Brush: FC<BrushProps>;
+    var Toolbar: FC<ToolbarProps>;
+    var Sonify: FC<SonifyProps>;
+}
+interface AreaProps {
+    /** The series to draw. Must exist on both the rows and the config. */
+    dataKey: string;
+    variant?: AreaVariant;
+    strokeVariant?: AreaStrokeVariant;
+    strokeWidth?: number;
+    curveType?: ChartCurveType;
+    animationType?: ChartRevealType;
+    connectNulls?: boolean;
+    /** Lets a click on this area select it, dimming the rest. */
+    isClickable?: boolean;
+    /** `<AreaChart.Dot>`, `<AreaChart.ActiveDot>` and `<AreaChart.Values>`. */
+    children?: ReactNode;
+    areaProps?: ComponentProps<typeof Area>;
+}
+interface DotProps {
+    variant?: ChartDotVariant;
+}
+interface ChartTooltipSlotProps {
+    variant?: ChartTooltipVariant;
+    roundness?: ChartTooltipRoundness;
+    /** Shows the tooltip at this row before anything is hovered. */
+    defaultIndex?: number;
+    /** The crosshair that follows the pointer along the axis. */
+    cursor?: boolean;
+}
+interface ChartLegendSlotProps {
+    variant?: ChartLegendVariant;
+    align?: ChartLegendAlign;
+    verticalAlign?: 'top' | 'middle' | 'bottom';
+    /** Makes each entry a button that selects its series. */
+    isClickable?: boolean;
+}
+
+export { AreaChart, type AreaChartProps, type AreaProps, type AreaStackType, type AreaStrokeVariant, type AreaVariant, type ChartCurveType, type ChartLegendSlotProps, type ChartTooltipSlotProps, type ChartXAxisProps, type ChartYAxisProps, type DotProps, AreaChart as default };