@nebulahome/package-sdk 0.0.0-stage → 1.0.1

package/dist/chunks/node-problems.js

@@ -0,0 +1,54 @@
+//#region src/generate/problems.ts
+/**
+* What is wrong with a package's declaration, every problem at once and each with where it is,
+* so an author fixes them in one pass rather than one build at a time.
+*/
+/** Thrown when a declaration does not hold together. */
+var PackageConfigError = class extends Error {
+	/** Every problem, one line each: `cards[0].options.days: …`. */
+	problems;
+	/**
+	* Gathers the problems.
+	*
+	* @param problems - Each problem, with where it is.
+	*/
+	constructor(problems) {
+		super(`The package does not hold together:\n${problems.map((problem) => `  - ${problem}`).join("\n")}`);
+		this.name = "PackageConfigError";
+		this.problems = problems;
+	}
+};
+/**
+* A place to gather problems.
+*
+* @returns It.
+*/
+function problems() {
+	const list = [];
+	return {
+		/**
+		* Records a problem.
+		*
+		* @param path - Where in the declaration, or empty for the whole of it.
+		* @param message - What is wrong.
+		*/
+		add: (path, message) => {
+			list.push(path === "" ? message : `${path}: ${message}`);
+		},
+		list
+	};
+}
+/**
+* A path from its parts, as a declaration is written: `cards[0].options.days`.
+*
+* @param parts - The keys and indexes.
+* @returns The path.
+*/
+function pathOf(parts) {
+	return parts.reduce((path, part) => {
+		if (typeof part === "number") return `${path}[${String(part)}]`;
+		return path === "" ? String(part) : `${path}.${String(part)}`;
+	}, "");
+}
+//#endregion
+export { pathOf as n, problems as r, PackageConfigError as t };

package/dist/chunks/props.d.ts

@@ -0,0 +1,68 @@
+import { O as OptionField, S as FormValues, T as NoFields, d as EntityTypeDefinition, lt as EntityId, x as Fields } from "./json.js";
+//#region src/definitions/card.d.ts
+/** The cells a card can cover: 1×1, 2×1, 2×2 and 2×3. */
+type CardSize = 'small' | 'wide' | 'medium' | 'large';
+/** How a card fills its frame: inside its padding, or to its edges. */
+type CardPadding = 'default' | 'none';
+/** A card, as declared. */
+type CardDefinition<TId extends string = string, TSize extends CardSize = CardSize, TOptions extends Fields<OptionField> = Fields<OptionField>> = {
+  readonly kind: 'card';
+  readonly id: TId;
+  readonly name: string;
+  readonly description?: string;
+  /** A catalogue icon id, as everywhere in the interface. */
+  readonly icon: string;
+  /** The sizes it can be drawn at; the first is what it is added at. `['medium']` when not said. */
+  readonly sizes?: readonly TSize[];
+  readonly padding?: CardPadding;
+  /** What its inspector asks, per card on a dashboard. */
+  readonly options?: TOptions;
+};
+/** The sizes a card is drawn at. */
+type SizeOf<TCard> = TCard extends CardDefinition<string, infer TSize> ? TSize : CardSize;
+/** The values of a card's options, defaults applied. */
+type OptionsOf<TCard> = TCard extends CardDefinition<string, CardSize, infer TOptions> ? FormValues<TOptions> : never;
+/**
+ * Declares a card.
+ *
+ * @param card - Its id, name, icon, sizes and options.
+ * @returns The card, for `definePackage`'s `cards` and for its component's props.
+ */
+declare function defineCard<const TId extends string, const TSize extends CardSize = 'medium', const TOptions extends Fields<OptionField> = NoFields>(card: Omit<CardDefinition<TId, TSize, TOptions>, 'kind'>): CardDefinition<TId, TSize, TOptions>;
+//#endregion
+//#region src/props.d.ts
+/** A component of the package: a function of its props, or one React wrapped (`memo`). */
+type PackageComponent<TProps> = ((props: TProps) => unknown) | {
+  readonly $$typeof: symbol;
+};
+/** How a component is loaded: `() => import('./card.js')`, to it or to a module that exports it. */
+type Loader<TProps> = () => Promise<PackageComponent<TProps> | {
+  readonly default: PackageComponent<TProps>;
+}>;
+/** What the package's own page is given. */
+type PageProps = {
+  readonly packageId: string;
+};
+/** What a card is given. */
+type CardProps<TCard extends CardDefinition = CardDefinition> = {
+  readonly packageId: string;
+  readonly cardId: TCard['id'];
+  /** The card's declared name. */
+  readonly name: string;
+  /** What the owner titled this card, if anything. */
+  readonly title: string | null;
+  /** The size it is drawn at now. */
+  readonly size: SizeOf<TCard>;
+  /** What its inspector asked, defaults applied. */
+  readonly options: OptionsOf<TCard>;
+  /** Whether the dashboard is being edited: no interaction is expected. */
+  readonly isEditing: boolean;
+};
+/** What an entity view is given. */
+type EntityViewProps<TType extends EntityTypeDefinition = EntityTypeDefinition> = {
+  readonly packageId: string;
+  readonly entityId: EntityId;
+  readonly type: TType['id'];
+};
+//#endregion
+export { PageProps as a, CardSize as c, defineCard as d, PackageComponent as i, OptionsOf as l, EntityViewProps as n, CardDefinition as o, Loader as r, CardPadding as s, CardProps as t, SizeOf as u };

package/dist/chunks/version.js

@@ -0,0 +1,12 @@
+//#endregion
+//#region src/version.ts
+/**
+* The SDK's own version, read from its `package.json` when it is built.
+*
+* What a package records in its manifest's `sdk` range, and what the platform says it implements:
+* the two are compared before a package is installed or started (PACKAGES_DOCS.md 11).
+*/
+/** The SDK's own version, `1.0.0`. */
+const SDK_VERSION = "1.0.1";
+//#endregion
+export { SDK_VERSION as t };

package/dist/cli.d.ts

@@ -0,0 +1 @@
+export {}

package/dist/cli.js

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+import { t as PackageConfigError } from "./chunks/node-problems.js";
+import path from "node:path";
+import { parseArgs } from "node:util";
+//#region src/cli/index.ts
+/**
+* `nebulahome-package`: the command a package is checked, built and packed with
+* (PACKAGES_DOCS.md 8.2).
+*
+* ```
+* nebulahome-package validate        the declaration holds together, the way the platform reads it
+* nebulahome-package build           validate, then build both halves into dist/
+* nebulahome-package pack [--url u]  pack dist/ into <id>-<version>.tgz, and index-entry.json with --url
+* ```
+*
+* Every command takes `--root <folder>`, the package's folder - the working directory when not
+* said. A problem ends it with exit code 1, every problem printed.
+*
+* The build and the archive are loaded when a command needs them: the build imports Vite, the
+* package's own development dependency, so the help runs anywhere - `npx` in an empty folder - and
+* a command run without Vite says what to install.
+*/
+/** The tools a package is built with, as the README has them installed. */
+const BUILD_TOOLS = "pnpm add -D vite typescript react @types/react @vitejs/plugin-react tailwindcss @tailwindcss/vite";
+/** How the command is used. */
+const USAGE = `Usage: nebulahome-package <validate | build | pack> [--root <folder>] [--url <base>]
+
+  validate   check nebula.config.ts the way the platform reads a release
+  build      validate, then build the interface and the server into dist/
+  pack       pack dist/ into <id>-<version>.tgz; with --url, or on GitHub Actions, write
+             index-entry.json for the package index too
+`;
+/**
+* Writes a line for whoever runs the command.
+*
+* @param line - What it says.
+*/
+function say(line) {
+	process.stdout.write(`${line}\n`);
+}
+/**
+* Says whether an error is Node failing to find Vite: the SDK is not where the package's tools
+* are installed, or they are not installed yet.
+*
+* @param error - What was thrown.
+* @returns True when it is.
+*/
+function isViteMissing(error) {
+	return error instanceof Error && "code" in error && error.code === "ERR_MODULE_NOT_FOUND" && error.message.includes("'vite'");
+}
+/**
+* What to do when Vite is missing.
+*
+* @param command - The command that needs it.
+* @returns The lines to print.
+*/
+function viteMissing(command) {
+	return `nebulahome-package ${command} needs Vite, and it is not installed where the SDK is.
+Install the SDK and the tools a package is built with in the package's folder:
+
+  pnpm add @nebulahome/package-sdk
+  ${BUILD_TOOLS}
+
+then run the command from there: pnpm exec nebulahome-package ${command}
+`;
+}
+/**
+* Runs the command.
+*
+* @param args - Its arguments, after the program's name.
+* @returns Its exit code.
+*/
+async function run(args) {
+	const { positionals, values } = parseArgs({
+		args: [...args],
+		allowPositionals: true,
+		options: {
+			root: { type: "string" },
+			url: { type: "string" },
+			help: {
+				type: "boolean",
+				short: "h"
+			}
+		}
+	});
+	const [command] = positionals;
+	const root = path.resolve(values.root ?? ".");
+	if (values.help === true || command === void 0) {
+		say(USAGE);
+		return command === void 0 && values.help !== true ? 1 : 0;
+	}
+	try {
+		switch (command) {
+			case "validate": {
+				const { checkPackage } = await import("./chunks/node-build2.js");
+				const { generated } = await checkPackage({ root });
+				say(`${String(generated.manifest["name"])} ${String(generated.manifest["version"])} holds together.`);
+				return 0;
+			}
+			case "build": {
+				const { buildPackage } = await import("./chunks/node-build2.js");
+				const { generated, outDir } = await buildPackage({
+					root,
+					logLevel: "warn"
+				});
+				say(`Built ${String(generated.manifest["name"])} ${String(generated.manifest["version"])} into ${path.relative(root, outDir)}.`);
+				return 0;
+			}
+			case "pack": {
+				const [{ checkPackage }, { packRelease }] = await Promise.all([import("./chunks/node-build2.js"), import("./chunks/node-pack.js")]);
+				const { outDir } = await checkPackage({ root });
+				const packed = await packRelease({
+					root,
+					outDir,
+					...values.url === void 0 ? {} : { urlBase: values.url }
+				});
+				say(`Packed ${path.relative(root, packed.archive)} (${String(packed.size)} bytes, sha256 ${packed.sha256}).`);
+				say(packed.indexEntry === void 0 ? "Wrote no index-entry.json: pass --url <base> for the address the archive is released at." : `Wrote ${path.relative(root, packed.indexEntry)}.`);
+				return 0;
+			}
+			default:
+				process.stderr.write(`There is no command ${command}.\n\n${USAGE}`);
+				return 1;
+		}
+	} catch (error) {
+		if (error instanceof PackageConfigError) {
+			process.stderr.write(`${error.message}\n`);
+			return 1;
+		}
+		if (isViteMissing(error)) {
+			process.stderr.write(viteMissing(command));
+			return 1;
+		}
+		throw error;
+	}
+}
+//#endregion
+//#region src/cli/bin.ts
+/**
+* The `nebulahome-package` executable: runs the command, and ends with its exit code.
+*/
+process.exitCode = await run(process.argv.slice(2));
+//#endregion
+export {};

package/dist/components.d.ts

@@ -0,0 +1,381 @@
+import { ButtonHTMLAttributes, ComponentType, InputHTMLAttributes, ReactElement, ReactNode, SVGProps } from "react";
+//#region src/components/types.d.ts
+/** What a button does: the one thing a screen is for, anything else, or a destructive action. */
+type ButtonVariant = 'primary' | 'ghost' | 'danger';
+/** A button's size. */
+type ButtonSize = 'compact' | 'medium' | 'large';
+/** A button: a native button's attributes, a variant and a size. */
+type ButtonProps = ButtonHTMLAttributes<HTMLButtonElement> & {
+  readonly variant?: ButtonVariant;
+  readonly size?: ButtonSize;
+  /** Draws a spinner and refuses presses while true. */
+  readonly isBusy?: boolean;
+  readonly children: ReactNode;
+};
+/** A button with an icon and no text, named by `label`. */
+type IconButtonProps = Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'aria-label'> & {
+  readonly variant?: 'bare' | 'danger';
+  readonly size?: 'small' | 'medium' | 'large';
+  /** What pressing it does, for a screen reader and the tooltip. */
+  readonly label: string;
+  /** The glyph: an `Icon`. */
+  readonly children: ReactNode;
+};
+/** A catalogue icon, by the ids `icon` fields take. */
+type IconProps = Omit<SVGProps<SVGSVGElement>, 'id' | 'width' | 'height' | 'viewBox'> & {
+  readonly id: string;
+  /** In pixels; 20 when not said. */
+  readonly size?: number;
+};
+/** What a badge means. */
+type BadgeTone = 'neutral' | 'accent' | 'success' | 'warning' | 'danger';
+/** A short state. */
+type BadgeProps = {
+  readonly tone?: BadgeTone;
+  readonly size?: 'small' | 'medium';
+  readonly icon?: ReactNode;
+  readonly children: ReactNode;
+  readonly className?: string;
+};
+/** A titled section. */
+type PanelProps = {
+  readonly title: string;
+  /** `flat` for a panel inside another. */
+  readonly elevation?: 'raised' | 'flat';
+  /** What sits in the title's row: a button. */
+  readonly action?: ReactNode;
+  readonly children: ReactNode;
+  readonly className?: string;
+};
+/** A row of a panel: a title, a note under it, a control opposite. */
+type PanelRowProps = {
+  readonly title: ReactNode;
+  readonly note?: ReactNode;
+  readonly control?: ReactNode;
+  readonly children?: ReactNode;
+  readonly className?: string;
+};
+/** A note under a panel. */
+type PanelNoteProps = {
+  readonly children: ReactNode;
+};
+/** A card's two-line heading. */
+type CardHeadingProps = {
+  readonly title: string;
+  readonly subtitle?: string | null | undefined;
+  /** What sits opposite: a switch, a badge. */
+  readonly tail?: ReactNode;
+  /** Draws the title quieter, for something that cannot be read. */
+  readonly isMuted?: boolean;
+};
+/** A reading as a number and its unit. */
+type FigureProps = {
+  /** The number, already written. */
+  readonly value: string;
+  readonly unit?: string | null | undefined;
+  readonly size?: 'large' | 'medium' | 'small';
+  /** A colour for the number, when what it measures has one. */
+  readonly color?: string | undefined;
+};
+/** A state at a glance. */
+type StatusDotProps = {
+  readonly tone: 'success' | 'warning' | 'danger' | 'neutral' | 'accent';
+  /** What it means, for the tooltip and a screen reader. */
+  readonly title: string;
+  /** Pulses while something is being done. */
+  readonly isBusy?: boolean;
+};
+/** How far something has come. */
+type ProgressBarProps = {
+  /** 0 to 100; null pulses the whole bar. */
+  readonly percent: number | null;
+  /** What it is, for a screen reader. */
+  readonly label: string;
+};
+/** An explanation behind a small `i`. */
+type HintProps = {
+  readonly text: string;
+  readonly className?: string;
+};
+/** A labelled text input: an input's attributes, a label, and what it says under it. */
+type TextFieldProps = Omit<InputHTMLAttributes<HTMLInputElement>, 'id' | 'size'> & {
+  readonly label: string;
+  readonly isLabelHidden?: boolean;
+  readonly size?: 'compact' | 'medium' | 'large';
+  readonly error?: string | undefined;
+  readonly warning?: string | undefined;
+  readonly hint?: ReactNode;
+};
+/** One choice of a select or a segmented control. */
+type ControlOption<TValue extends string = string> = {
+  readonly value: TValue;
+  readonly label: string;
+};
+/** A labelled choice from a list. */
+type SelectFieldProps = {
+  readonly label: string;
+  readonly isLabelHidden?: boolean;
+  readonly options: readonly ControlOption[];
+  readonly value: string;
+  readonly onChange: (value: string) => void;
+  readonly disabled?: boolean;
+  readonly size?: 'compact' | 'medium' | 'large';
+  readonly error?: string | undefined;
+  readonly hint?: ReactNode;
+  readonly className?: string;
+};
+/** On or off. */
+type SwitchProps = {
+  readonly label: string;
+  readonly isOn: boolean;
+  readonly onChange: (isOn: boolean) => void;
+  readonly size?: 'small' | 'medium';
+  readonly disabled?: boolean;
+  readonly isBusy?: boolean;
+  readonly className?: string;
+};
+/** One of a few, side by side. */
+type SegmentedProps<TValue extends string = string> = {
+  readonly label: string;
+  readonly options: readonly ControlOption<TValue>[];
+  readonly value: TValue;
+  readonly onChange: (value: TValue) => void;
+  readonly size?: 'compact' | 'medium';
+  readonly disabled?: boolean;
+  readonly className?: string;
+};
+/** A value in a range. */
+type SliderProps = {
+  readonly label: string;
+  readonly isLabelHidden?: boolean;
+  readonly value: number;
+  readonly min: number;
+  readonly max: number;
+  readonly step?: number;
+  /** The value, written: `40 %`. */
+  readonly display: string;
+  readonly onChange: (value: number) => void;
+  /** Once the knob is let go. */
+  readonly onCommit?: ((value: number) => void) | undefined;
+  readonly fill?: 'accent' | 'warm';
+  readonly disabled?: boolean;
+  readonly className?: string;
+};
+/** A value by steps. */
+type StepperProps = {
+  readonly label: string;
+  readonly value: number;
+  readonly min: number;
+  readonly max: number;
+  readonly step: number;
+  /**
+   * Writes a value.
+   *
+   * @param value - The value.
+   * @returns It, written.
+   */
+  readonly format: (value: number) => string;
+  readonly onChange: (value: number) => void;
+  readonly disabled?: boolean;
+  readonly className?: string;
+};
+/** A colour of the tag palette. */
+type TagColor = 'red' | 'orange' | 'amber' | 'yellow' | 'lime' | 'green' | 'teal' | 'cyan' | 'blue' | 'indigo' | 'violet' | 'pink';
+/** A coloured tag. */
+type TagChipProps = {
+  readonly color: TagColor;
+  readonly children: string;
+  readonly size?: 'small' | 'medium';
+  /** Shows a remove button that calls this. */
+  readonly onRemove?: (() => void) | undefined;
+  readonly className?: string;
+};
+/** A dialog, drawn inside the package's scope. */
+type ModalProps = {
+  readonly isOpen: boolean;
+  readonly onClose: () => void;
+  readonly title: string;
+  readonly description?: ReactNode;
+  readonly size?: 'small' | 'medium' | 'large';
+  readonly closesOnBackdrop?: boolean;
+  readonly children: ReactNode;
+  /** Its buttons. */
+  readonly footer?: ReactNode;
+};
+/** What `cn` joins: classes, conditions, lists of them. */
+type ClassValue = string | number | bigint | boolean | null | undefined | readonly ClassValue[] | Readonly<Record<string, unknown>>;
+/** What the interface lends to implement `/components`. */
+type ComponentsHost = {
+  readonly Button: ComponentType<ButtonProps>;
+  readonly IconButton: ComponentType<IconButtonProps>;
+  readonly Icon: ComponentType<IconProps>;
+  readonly Badge: ComponentType<BadgeProps>;
+  readonly Panel: ComponentType<PanelProps>;
+  readonly PanelRow: ComponentType<PanelRowProps>;
+  readonly PanelNote: ComponentType<PanelNoteProps>;
+  readonly CardHeading: ComponentType<CardHeadingProps>;
+  readonly Figure: ComponentType<FigureProps>;
+  readonly StatusDot: ComponentType<StatusDotProps>;
+  readonly ProgressBar: ComponentType<ProgressBarProps>;
+  readonly Hint: ComponentType<HintProps>;
+  readonly TextField: ComponentType<TextFieldProps>;
+  readonly SelectField: ComponentType<SelectFieldProps>;
+  readonly Switch: ComponentType<SwitchProps>;
+  readonly Segmented: ComponentType<SegmentedProps>;
+  readonly Slider: ComponentType<SliderProps>;
+  readonly Stepper: ComponentType<StepperProps>;
+  readonly TagChip: ComponentType<TagChipProps>;
+  readonly Modal: ComponentType<ModalProps>;
+  readonly cn: (...classes: readonly ClassValue[]) => string;
+};
+//#endregion
+//#region src/components/index.d.ts
+/**
+ * An action.
+ *
+ * @param props - A native button's attributes, a variant and a size.
+ * @returns The button.
+ */
+export declare function Button(props: ButtonProps): ReactElement;
+/**
+ * An action with an icon and no text.
+ *
+ * @param props - What it does, its glyph, its variant and size.
+ * @returns The button.
+ */
+export declare function IconButton(props: IconButtonProps): ReactElement;
+/**
+ * A catalogue icon.
+ *
+ * @param props - Its id and size.
+ * @returns The icon.
+ */
+export declare function Icon(props: IconProps): ReactElement;
+/**
+ * A short state.
+ *
+ * @param props - Its tone, size and text.
+ * @returns The badge.
+ */
+export declare function Badge(props: BadgeProps): ReactElement;
+/**
+ * A titled section.
+ *
+ * @param props - Its title, action and content.
+ * @returns The panel.
+ */
+export declare function Panel(props: PanelProps): ReactElement;
+/**
+ * A row of a panel.
+ *
+ * @param props - Its title, note and control.
+ * @returns The row.
+ */
+export declare function PanelRow(props: PanelRowProps): ReactElement;
+/**
+ * A note under a panel.
+ *
+ * @param props - What it says.
+ * @returns The note.
+ */
+export declare function PanelNote(props: PanelNoteProps): ReactElement;
+/**
+ * A card's two-line heading, as the dashboard's own cards draw it.
+ *
+ * @param props - Its title, subtitle and tail.
+ * @returns The heading.
+ */
+export declare function CardHeading(props: CardHeadingProps): ReactElement;
+/**
+ * A reading as a number and its unit.
+ *
+ * @param props - The number, its unit and size.
+ * @returns The figure.
+ */
+export declare function Figure(props: FigureProps): ReactElement;
+/**
+ * A state at a glance.
+ *
+ * @param props - Its tone and meaning.
+ * @returns The dot.
+ */
+export declare function StatusDot(props: StatusDotProps): ReactElement;
+/**
+ * How far something has come.
+ *
+ * @param props - The percentage and what it is.
+ * @returns The bar.
+ */
+export declare function ProgressBar(props: ProgressBarProps): ReactElement;
+/**
+ * An explanation behind a small `i`.
+ *
+ * @param props - The explanation.
+ * @returns The hint.
+ */
+export declare function Hint(props: HintProps): ReactElement;
+/**
+ * A labelled text input.
+ *
+ * @param props - An input's attributes, its label and what it says under it.
+ * @returns The field.
+ */
+export declare function TextField(props: TextFieldProps): ReactElement;
+/**
+ * A labelled choice from a list.
+ *
+ * @param props - Its label, options and value.
+ * @returns The field.
+ */
+export declare function SelectField(props: SelectFieldProps): ReactElement;
+/**
+ * On or off.
+ *
+ * @param props - Its label and state.
+ * @returns The switch.
+ */
+export declare function Switch(props: SwitchProps): ReactElement;
+/**
+ * One of a few, side by side.
+ *
+ * @param props - Its label, options and value.
+ * @returns The control.
+ */
+export declare function Segmented<TValue extends string>(props: SegmentedProps<TValue>): ReactElement;
+/**
+ * A value in a range.
+ *
+ * @param props - Its label, range, value and how it is written.
+ * @returns The slider.
+ */
+export declare function Slider(props: SliderProps): ReactElement;
+/**
+ * A value by steps.
+ *
+ * @param props - Its label, range, step and how it is written.
+ * @returns The stepper.
+ */
+export declare function Stepper(props: StepperProps): ReactElement;
+/**
+ * A coloured tag.
+ *
+ * @param props - Its colour and text.
+ * @returns The tag.
+ */
+export declare function TagChip(props: TagChipProps): ReactElement;
+/**
+ * A dialog, drawn inside the package's scope.
+ *
+ * @param props - Whether it is open, its title, content and buttons.
+ * @returns The dialog.
+ */
+export declare function Modal(props: ModalProps): ReactElement;
+/**
+ * Joins class names, resolving Tailwind conflicts: the later class wins.
+ *
+ * @param classes - Classes, conditions, lists of them.
+ * @returns The class names.
+ */
+export declare function cn(...classes: readonly ClassValue[]): string;
+//#endregion
+export type { BadgeProps, BadgeTone, ButtonProps, ButtonSize, ButtonVariant, CardHeadingProps, ClassValue, ComponentsHost, ControlOption, FigureProps, HintProps, IconButtonProps, IconProps, ModalProps, PanelNoteProps, PanelProps, PanelRowProps, ProgressBarProps, SegmentedProps, SelectFieldProps, SliderProps, StatusDotProps, StepperProps, SwitchProps, TagChipProps, TagColor, TextFieldProps };