@dsh-stack/settings-panel 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,75 @@
-# Temporary Holding Version
+# @dsh-stack/settings-panel
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The canonical shape of a DSH Stack settings section.
+
+Every Stack settings section renders the same furniture: a titled header with a
+description, a vertical grid of options, selectable rows, and a close action.
+Before this package each section hand-rolled that shape with inline styles —
+`sidebar-settings`, `skin-settings` and `profile-ui` each carried their own
+copy. The copies drifted (different border tokens, different type scales), and
+the duplication was suppressed with `jscpd:ignore` markers rather than removed,
+which `.agents/AGENTS.md` forbids: there is exactly one implementation owner for
+every feature.
+
+This package is that owner. Sections compose it and contribute only their own
+content.
+
+## Exports
+
+| Export | Renders |
+| --- | --- |
+| `SettingsSection` | section frame: accessible label, header with title and description, and an option grid |
+| `SettingsOptionRow` | one selectable option row with a checkmark when selected — skins, profiles |
+| `SettingsToggleRow` | one labelled option row with a description and a checkbox — sidebar preferences |
+| `SettingsCloseButton` | the section's close action |
+
+## Slot seats
+
+Two settings slots are declared at runtime by hand-authored JavaScript that
+carries no TypeScript face, so their `SlotMap` types live here — in the package
+every Stack settings registrant already depends on.
+
+| Export | Seat | Filled by |
+| --- | --- | --- |
+| `SETTINGS_SECTION_ICON_SLOT` | `settings.section.icon` — one nav glyph per settings section, keyed by section id | whichever plugin owns the matching `settings.section` entry |
+| `SETTINGS_APPEARANCE_TAB_SLOT` | `settings.appearance.tab` — one page inside the Appearance section | the packages owning the theme studio, skins, icons and themes |
+
+`settings.appearance.tab` is what makes Appearance a single settings
+destination without its owner importing the three feature packages whose pages
+it shows; see `.agents/notes/decisions/settings-section-composition.md`.
+
+## Usage
+
+```tsx
+import {
+  SettingsSection,
+  SettingsOptionRow,
+  SettingsCloseButton,
+} from "@dsh-stack/settings-panel";
+
+<SettingsSection
+  label="Skins"
+  title="Skins"
+  description="Change the DSH Stack visual identity."
+  onClose={close}
+>
+  {skins.map((skin) => (
+    <SettingsOptionRow
+      key={skin.id}
+      label={skin.label}
+      selected={skin.id === active}
+      onSelect={() => setActive(skin.id)}
+    />
+  ))}
+</SettingsSection>
+```
+
+`SettingsSection` renders `SettingsCloseButton` itself when given `onClose`.
+
+## Styling
+
+Presentation lives here as inline style objects, matching how the surrounding
+Stack settings surfaces are written today; there is no CSS-module build step in
+this layer. Colours are expressed with `color-mix(in srgb, currentColor …)` so a
+section inherits the host shell's palette and stays correct under every skin
+without importing theme tokens.

package/lib/appearance-tab-slot.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Owner share of one Appearance tab. The section owns tab selection and the
+ * tab strip; a tab draws its own body and receives the same `close` affordance
+ * a top-level section gets, so a tab that used to be its own section keeps
+ * whatever close action it already rendered.
+ */
+export interface SettingsAppearanceTabOwnerProps {
+    /** Close the settings panel (the shell owns the open state). */
+    close: () => void;
+}
+declare module "@deepseek-ai/dsh-client-ui-slots" {
+    interface SlotMap {
+        /**
+         * One page inside the Appearance settings section. Options carry the tab
+         * identity: `id` (tab key, drives `only` filtering), `order` (tab
+         * position) and `label` (registrant-owned tab text). Declared at runtime
+         * by the Appearance section; registrants never depend on one another.
+         */
+        "settings.appearance.tab": {
+            kind: "list";
+            scope: "root";
+            owner: SettingsAppearanceTabOwnerProps;
+        };
+    }
+}
+/**
+ * The seat's slot key, re-exported so registrants name it once instead of
+ * repeating the string literal at every `inject`/`register` pair.
+ */
+export declare const SETTINGS_APPEARANCE_TAB_SLOT: "settings.appearance.tab";

package/lib/appearance-tab-slot.js

@@ -0,0 +1,5 @@
+/**
+ * The seat's slot key, re-exported so registrants name it once instead of
+ * repeating the string literal at every `inject`/`register` pair.
+ */
+export const SETTINGS_APPEARANCE_TAB_SLOT = "settings.appearance.tab";

package/lib/index.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Canonical settings-section furniture shared by every Stack settings surface.
+ *
+ * `sidebar-settings`, `skin-settings` and `profile-ui` each used to hand-roll
+ * the same section frame, option grid and selectable row with inline styles.
+ * The copies drifted apart and the duplication was suppressed with
+ * `jscpd:ignore` markers instead of removed. This module is the single owner of
+ * that shape; sections contribute only their own content.
+ *
+ * @module @dsh-stack/settings-panel
+ */
+import type { ReactNode } from "react";
+export { SETTINGS_SECTION_ICON_SLOT } from "./section-icon-slot.js";
+export type { SettingsSectionIconOwnerProps } from "./section-icon-slot.js";
+export { SETTINGS_APPEARANCE_TAB_SLOT } from "./appearance-tab-slot.js";
+export type { SettingsAppearanceTabOwnerProps } from "./appearance-tab-slot.js";
+export interface SettingsSectionProps {
+    /** Accessible name for the section landmark. */
+    readonly label: string;
+    /** Heading shown at the top of the section. */
+    readonly title: string;
+    /** Supporting copy under the heading. */
+    readonly description?: string;
+    /** Option rows; rendered inside the shared option grid. */
+    readonly children: ReactNode;
+    /** Close handler; when supplied the section renders its own close action. */
+    readonly onClose?: () => void;
+    /** Label for the close action. */
+    readonly closeLabel?: string;
+}
+/**
+ * The frame every Stack settings section renders inside.
+ * @param props - section content and close behaviour.
+ * @returns the section landmark, header, option grid and close action.
+ */
+export declare function SettingsSection({ label, title, description, children, onClose, closeLabel, }: SettingsSectionProps): import("react").JSX.Element;
+export interface SettingsOptionRowProps {
+    /** Text shown on the row. */
+    readonly label: string;
+    /** Whether this row is the current selection. */
+    readonly selected: boolean;
+    /** Invoked when the row is chosen. */
+    readonly onSelect: () => void;
+    /**
+     * Mark rendered on the selected row. Sections that own an icon set pass their
+     * own glyph; the default keeps the row usable without one.
+     */
+    readonly selectedMark?: ReactNode;
+}
+/**
+ * One selectable option in a settings section — a skin, a profile, a theme.
+ * @param props - row label, selection state and select handler.
+ * @returns a pressable row that marks itself when selected.
+ */
+export declare function SettingsOptionRow({ label, selected, onSelect, selectedMark, }: SettingsOptionRowProps): import("react").JSX.Element;
+export interface SettingsToggleRowProps {
+    /** Element id linking the row's label to its checkbox. */
+    readonly id: string;
+    /** Text shown on the row. */
+    readonly label: string;
+    /** Supporting copy under the label. */
+    readonly description: string;
+    /** Current value. */
+    readonly checked: boolean;
+    /** Invoked with the new value when the row is toggled. */
+    readonly onChange: (value: boolean) => void;
+}
+/**
+ * One boolean preference in a settings section.
+ * @param props - row identity, copy, value and change handler.
+ * @returns a labelled row wrapping a checkbox.
+ */
+export declare function SettingsToggleRow({ id, label, description, checked, onChange, }: SettingsToggleRowProps): import("react").JSX.Element;
+export interface SettingsCloseButtonProps {
+    /** Button text. */
+    readonly label: string;
+    /** Invoked when the button is pressed. */
+    readonly onClose: () => void;
+}
+/**
+ * The close action a settings section renders below its options.
+ * @param props - button label and close handler.
+ * @returns the close button.
+ */
+export declare function SettingsCloseButton({ label, onClose }: SettingsCloseButtonProps): import("react").JSX.Element;

package/lib/index.js

@@ -0,0 +1,79 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+export { SETTINGS_SECTION_ICON_SLOT } from "./section-icon-slot.js";
+export { SETTINGS_APPEARANCE_TAB_SLOT } from "./appearance-tab-slot.js";
+/** Vertical rhythm between a section's option rows, in pixels. */
+const OPTION_GAP = 8;
+/** Height of a single option row, in pixels. */
+const ROW_MIN_HEIGHT = 46;
+/** Corner radius shared by every option row, in pixels. */
+const ROW_RADIUS = 9;
+/**
+ * Hairline that reads correctly on any skin: it is derived from the inherited
+ * text colour rather than a theme token, so a section stays legible wherever
+ * the host shell mounts it.
+ */
+const ROW_BORDER = "1px solid color-mix(in srgb, currentColor 14%, transparent)";
+/** Fill applied to the row representing the current selection. */
+const ROW_SELECTED_BACKGROUND = "color-mix(in srgb, currentColor 7%, transparent)";
+const sectionStyle = { maxWidth: 720, display: "grid", gap: 18 };
+const titleStyle = { margin: 0, fontSize: 17, fontWeight: 650 };
+const descriptionStyle = {
+    margin: "6px 0 0",
+    fontSize: 13,
+    lineHeight: 1.5,
+    opacity: 0.68,
+};
+const optionGridStyle = { display: "grid", gap: OPTION_GAP };
+const rowBaseStyle = {
+    display: "flex",
+    alignItems: "center",
+    justifyContent: "space-between",
+    gap: 12,
+    minHeight: ROW_MIN_HEIGHT,
+    padding: "0 12px",
+    borderRadius: ROW_RADIUS,
+    border: ROW_BORDER,
+    color: "inherit",
+    font: "inherit",
+    textAlign: "left",
+    cursor: "pointer",
+};
+const rowLabelStackStyle = { display: "grid", gap: 2 };
+const rowLabelStyle = { fontSize: 14 };
+const rowDescriptionStyle = { fontSize: 12, lineHeight: 1.4, opacity: 0.68 };
+const closeButtonStyle = { justifySelf: "start" };
+/**
+ * The frame every Stack settings section renders inside.
+ * @param props - section content and close behaviour.
+ * @returns the section landmark, header, option grid and close action.
+ */
+export function SettingsSection({ label, title, description, children, onClose, closeLabel = "Close", }) {
+    return (_jsxs("section", { "aria-label": label, style: sectionStyle, children: [_jsxs("header", { children: [_jsx("h2", { style: titleStyle, children: title }), description === undefined ? null : _jsx("p", { style: descriptionStyle, children: description })] }), _jsx("div", { style: optionGridStyle, children: children }), onClose === undefined ? null : _jsx(SettingsCloseButton, { label: closeLabel, onClose: onClose })] }));
+}
+/**
+ * One selectable option in a settings section — a skin, a profile, a theme.
+ * @param props - row label, selection state and select handler.
+ * @returns a pressable row that marks itself when selected.
+ */
+export function SettingsOptionRow({ label, selected, onSelect, selectedMark, }) {
+    return (_jsxs("button", { type: "button", "aria-pressed": selected, onClick: onSelect, style: {
+            ...rowBaseStyle,
+            background: selected ? ROW_SELECTED_BACKGROUND : "transparent",
+        }, children: [_jsx("span", { style: rowLabelStyle, children: label }), selected ? (selectedMark ?? _jsx("span", { "aria-hidden": "true", children: "\u2713" })) : null] }));
+}
+/**
+ * One boolean preference in a settings section.
+ * @param props - row identity, copy, value and change handler.
+ * @returns a labelled row wrapping a checkbox.
+ */
+export function SettingsToggleRow({ id, label, description, checked, onChange, }) {
+    return (_jsxs("label", { htmlFor: id, style: { ...rowBaseStyle, padding: "10px 12px" }, children: [_jsxs("span", { style: rowLabelStackStyle, children: [_jsx("span", { style: rowLabelStyle, children: label }), _jsx("span", { style: rowDescriptionStyle, children: description })] }), _jsx("input", { id: id, type: "checkbox", checked: checked, onChange: (event) => onChange(event.target.checked) })] }));
+}
+/**
+ * The close action a settings section renders below its options.
+ * @param props - button label and close handler.
+ * @returns the close button.
+ */
+export function SettingsCloseButton({ label, onClose }) {
+    return (_jsx("button", { type: "button", onClick: onClose, style: closeButtonStyle, children: label }));
+}

package/lib/section-icon-slot.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Owner share of a section glyph. The shell renders the nav cell and passes
+ * nothing: the glyph draws itself at its own size, inheriting `currentColor`
+ * from the nav row so selection and hover states stay the shell's business.
+ */
+export interface SettingsSectionIconOwnerProps {
+    /** Marker field: glyph owner props are intentionally empty. */
+    children?: never;
+}
+declare module "@deepseek-ai/dsh-client-ui-slots" {
+    interface SlotMap {
+        /**
+         * One nav glyph per settings section, keyed by the section's `id`. A
+         * section with no entry here falls back to the shell's own mark for that
+         * id, so the nav never renders a blank cell.
+         */
+        "settings.section.icon": {
+            kind: "list";
+            scope: "root";
+            owner: SettingsSectionIconOwnerProps;
+        };
+    }
+}
+/**
+ * The seat's slot key, re-exported so registrants name it once instead of
+ * repeating the string literal at every `inject`/`register` pair.
+ */
+export declare const SETTINGS_SECTION_ICON_SLOT: "settings.section.icon";

package/lib/section-icon-slot.js

@@ -0,0 +1,5 @@
+/**
+ * The seat's slot key, re-exported so registrants name it once instead of
+ * repeating the string literal at every `inject`/`register` pair.
+ */
+export const SETTINGS_SECTION_ICON_SLOT = "settings.section.icon";

package/package.json

@@ -1,6 +1,45 @@
 {
   "name": "@dsh-stack/settings-panel",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.typecheck.json --noEmit",
+    "verify": "node verify.mjs"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-client-ui-slots": "0.2.0-rc.2",
+    "react": "^18.2.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-client-ui-slots": "0.2.0-rc.2",
+    "@types/react": "~18.3.1",
+    "react": "^18.3.1",
+    "typescript": "^6.0.3"
+  },
+  "stack": {
+    "kind": "plugin",
+    "id": "stack.ui.settings-panel"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "lib",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/marius-patrik/dsh-stack.git",
+    "directory": "plugins/settings-panel"
+  }
+}