@mystravil/hardpoint 0.0.0-stage → 0.2.0

package/dist/components/AppShell.svelte.d.ts

@@ -0,0 +1,77 @@
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+/**
+ * One place the app's navigation leads to. The same list serves every
+ * navigation form: the bottom bar or the drawer on compact widths, the
+ * rail and the sidebar from 600px.
+ */
+export type AppShellDestination = {
+    /** Where the link goes. A plain `<a href>`, so any router handles it. */
+    href: string;
+    /**
+     * A short fixed label, set in caps. About six letters fit five across a
+     * 320px phone and the 80px rail; a longer label ends in an ellipsis.
+     */
+    label: string;
+    /**
+     * A glyph beside or above the label: an inline `<svg>` drawn in
+     * `currentColor` with `aria-hidden="true"`. It fills a 20px square, so
+     * give it a `viewBox` and no `width` or `height`.
+     */
+    icon?: Snippet;
+};
+/**
+ * The navigation below 600px: a bottom bar of the destinations, or a
+ * drawer that a menu button at the left of the header opens.
+ */
+export type AppShellCompactNav = 'bar' | 'drawer';
+/**
+ * The navigation from 900px: a sidebar of rows, or the rail that every
+ * width from 600 to 899px shows.
+ */
+export type AppShellWideNav = 'sidebar' | 'rail';
+export type AppShellProps = Omit<HTMLAttributes<HTMLDivElement>, 'title' | 'children'> & {
+    /** The view title: a fixed string the app defines, set in caps in the header. */
+    title: string;
+    /**
+     * The left of the header: the app's wordmark, usually a link home. Give
+     * a link here at least `--hit-target` height.
+     */
+    brand?: Snippet;
+    /**
+     * Page controls: filters or the row of page actions. At the right of the
+     * header row from 1200px; below that, their own row under the header.
+     */
+    controls?: Snippet;
+    /**
+     * Three to five destinations: the bottom bar or the drawer below 600px,
+     * the rail from 600px, the sidebar or the rail from 900px.
+     */
+    destinations?: AppShellDestination[];
+    /**
+     * The `href` of the current destination; it gets `aria-current="page"`.
+     * The app decides which destination a nested page belongs to.
+     */
+    current?: string;
+    /** Below 600px: `bar` (default) or `drawer`. */
+    compactNav?: AppShellCompactNav;
+    /** From 900px: `sidebar` (default) or `rail`. */
+    wideNav?: AppShellWideNav;
+    /** Whether the drawer is open. It closes when the window reaches 600px. */
+    drawerOpen?: boolean;
+    /** The accessible name of the navigation. */
+    navLabel?: string;
+    /** The menu button's accessible name and the drawer's caps title. */
+    menuLabel?: string;
+    /** The accessible name of the drawer's close button. */
+    closeLabel?: string;
+    /** The id of `<main>`, the skip link's target. */
+    mainId?: string;
+    /** The skip link's text, shown on keyboard focus. */
+    skipLabel?: string;
+    /** The view's content, rendered inside `<main>`. */
+    children: Snippet;
+};
+declare const AppShell: import("svelte").Component<AppShellProps, {}, "drawerOpen">;
+type AppShell = ReturnType<typeof AppShell>;
+export default AppShell;

package/dist/components/Button.svelte

@@ -0,0 +1,174 @@
+<script lang="ts" module>
+	import { Button as BitsButton } from 'bits-ui';
+
+	export type ButtonVariant = 'primary' | 'secondary' | 'tertiary';
+
+	export type ButtonProps = BitsButton.RootProps & {
+		/**
+		 * `primary`: solid titanium block, for the view's one group of solid
+		 * blocks. `secondary` (default): outlined. `tertiary`: caps label only.
+		 */
+		variant?: ButtonVariant;
+		/** Ends the label in a small ▸: the button opens another view. */
+		opens?: boolean;
+		/**
+		 * A square, icon-only button (height and width are `--control-height`).
+		 * It has no visible label, so it needs an accessible name: pass
+		 * `aria-label`.
+		 */
+		icon?: boolean;
+	};
+</script>
+
+<script lang="ts">
+	let {
+		variant = 'secondary',
+		opens = false,
+		icon = false,
+		class: className,
+		ref = $bindable(null),
+		children,
+		...rest
+	}: ButtonProps = $props();
+</script>
+
+<!--
+	An <a> when `href` is set, a <button> otherwise (Bits UI Button.Root). A
+	disabled link renders without href, with aria-disabled="true" and
+	tabindex -1; a disabled <button> is not focusable.
+-->
+<BitsButton.Root
+	bind:ref
+	class={['hp-button', 'hp-label', className]}
+	data-variant={variant}
+	data-opens={opens || undefined}
+	data-icon={icon || undefined}
+	{...rest}
+>
+	{@render children?.()}
+</BitsButton.Root>
+
+<style>
+	/* Bits UI renders the element, so the root class reaches it from the
+	   outside: the rules are :global, keyed on .hp-button and its data-*. */
+	:global(.hp-button) {
+		display: inline-flex;
+		align-items: center;
+		justify-content: space-between;
+		gap: var(--space-4);
+		box-sizing: border-box;
+		height: var(--control-height);
+		/* The visible box is the hit area: 36px fine, 44px coarse, and never
+		   narrower than --hit-target for a short label. */
+		min-width: var(--hit-target);
+		padding: 0 var(--space-3);
+		border: 0;
+		background: transparent;
+		color: var(--text);
+		font-family: var(--sans);
+		text-decoration: none;
+		white-space: nowrap;
+		cursor: pointer;
+		-webkit-tap-highlight-color: transparent;
+	}
+
+	/* ---- Variants ---------------------------------------------------- */
+
+	/* Solid titanium block with a black label. */
+	:global(.hp-button[data-variant='primary']) {
+		background: var(--accent);
+		color: var(--canvas);
+	}
+	/* Outlined: a 3:1 boundary, titanium label, black fill. */
+	:global(.hp-button[data-variant='secondary']) {
+		border: 1px solid var(--border-control);
+		background: var(--canvas);
+	}
+	/* The label alone. */
+	:global(.hp-button[data-variant='tertiary']) {
+		background: transparent;
+	}
+
+	/* ---- Opens another view: a small ▸ drawn in CSS ------------------ */
+
+	:global(.hp-button[data-opens]::after) {
+		content: '';
+		flex: none;
+		width: 6px;
+		height: 8px;
+		background: currentColor;
+		clip-path: polygon(0 0, 100% 50%, 0 100%);
+	}
+
+	/* ---- Icon only: a square ----------------------------------------- */
+
+	:global(.hp-button[data-icon]) {
+		justify-content: center;
+		width: var(--control-height);
+		padding: 0;
+	}
+	/* The icon is the consumer's inline <svg>; it draws in currentColor. */
+	:global(.hp-button svg) {
+		flex: none;
+	}
+	:global(.hp-button[data-icon] svg) {
+		width: var(--space-4);
+		height: var(--space-4);
+	}
+
+	/* ---- Hover: fine pointers only ----------------------------------- */
+
+	@media (hover: hover) and (pointer: fine) {
+		:global(.hp-button) {
+			transition:
+				background-color var(--dur-hover) var(--settle),
+				color var(--dur-hover) var(--settle);
+		}
+		:global(.hp-button:active:not(:disabled):not([aria-disabled='true'])) {
+			transition-duration: var(--dur-press);
+		}
+		:global(.hp-button[data-variant='primary']:hover:not(:disabled):not([aria-disabled='true'])) {
+			background: var(--muted);
+		}
+		:global(.hp-button[data-variant='secondary']:hover:not(:disabled):not([aria-disabled='true'])),
+		:global(.hp-button[data-variant='tertiary']:hover:not(:disabled):not([aria-disabled='true'])) {
+			background: var(--surface-hover);
+		}
+		/* The tint alone barely shows (1.03:1), so the label also underlines. */
+		:global(.hp-button[data-variant='tertiary']:hover:not(:disabled):not([aria-disabled='true'])) {
+			text-decoration: underline;
+			text-decoration-thickness: 1px;
+			text-underline-offset: 0.3em;
+		}
+	}
+
+	/* ---- Press: after hover, so it wins while the pointer is down ----- */
+
+	:global(.hp-button[data-variant='primary']:active:not(:disabled):not([aria-disabled='true'])) {
+		background: var(--muted);
+	}
+	/* One step past the hover tint, so a press reads on a phone too. */
+	:global(.hp-button[data-variant='secondary']:active:not(:disabled):not([aria-disabled='true'])),
+	:global(.hp-button[data-variant='tertiary']:active:not(:disabled):not([aria-disabled='true'])) {
+		background: var(--surface-raised);
+	}
+
+	/* ---- Disabled: muted ink. A <button> is not focusable; a link has
+	   no href. -------------------------------------------------------- */
+
+	:global(.hp-button:disabled),
+	:global(.hp-button[aria-disabled='true']) {
+		color: var(--muted);
+		cursor: not-allowed;
+	}
+	:global(.hp-button[data-variant='primary']:disabled),
+	:global(.hp-button[data-variant='primary'][aria-disabled='true']) {
+		/* --muted is 4.9:1 on the band. */
+		background: var(--surface-band);
+	}
+	:global(.hp-button[data-variant='secondary']:disabled),
+	:global(.hp-button[data-variant='secondary'][aria-disabled='true']) {
+		/* An off control needs no 3:1 boundary. */
+		border-color: var(--border);
+	}
+</style>

package/dist/components/Button.svelte.d.ts

@@ -0,0 +1,20 @@
+import { Button as BitsButton } from 'bits-ui';
+export type ButtonVariant = 'primary' | 'secondary' | 'tertiary';
+export type ButtonProps = BitsButton.RootProps & {
+    /**
+     * `primary`: solid titanium block, for the view's one group of solid
+     * blocks. `secondary` (default): outlined. `tertiary`: caps label only.
+     */
+    variant?: ButtonVariant;
+    /** Ends the label in a small ▸: the button opens another view. */
+    opens?: boolean;
+    /**
+     * A square, icon-only button (height and width are `--control-height`).
+     * It has no visible label, so it needs an accessible name: pass
+     * `aria-label`.
+     */
+    icon?: boolean;
+};
+declare const Button: import("svelte").Component<ButtonProps, {}, "ref">;
+type Button = ReturnType<typeof Button>;
+export default Button;

package/dist/components/Checkbox.svelte

@@ -0,0 +1,235 @@
+<script lang="ts" module>
+	import { Checkbox as BitsCheckbox } from 'bits-ui';
+
+	/** Attributes and handlers not listed here go to the checkbox button. */
+	export type CheckboxProps = Omit<BitsCheckbox.RootProps, 'child' | 'children' | 'ref'> & {
+		/**
+		 * The text beside the box, as written (never caps). Pressing it, or
+		 * anywhere on the box's row, toggles the box. Without it, give the box
+		 * an accessible name with `aria-label`.
+		 */
+		label?: string;
+		/**
+		 * A Tag after the label, such as "Recommended": a short fixed string the
+		 * app defines, set in caps. It is part of the box's accessible name and
+		 * shows only with a `label`.
+		 */
+		tag?: string;
+		/** A second line in `--muted` under the label, read out as the box's description. */
+		hint?: string;
+		/** The checkbox button. */
+		ref?: HTMLElement | null;
+	};
+</script>
+
+<script lang="ts">
+	import Tag from './Tag.svelte';
+
+	const uid = $props.id();
+
+	let {
+		checked = $bindable(false),
+		indeterminate = $bindable(false),
+		label,
+		tag,
+		hint,
+		id = uid,
+		ref = $bindable(null),
+		class: className,
+		'aria-describedby': describedBy,
+		...rest
+	}: CheckboxProps = $props();
+
+	const hintId = $derived(`${id}-hint`);
+	const describedByIds = $derived([hint ? hintId : null, describedBy].filter(Boolean).join(' ') || undefined);
+</script>
+
+<!--
+	A Bits UI Checkbox: a <button role="checkbox"> with aria-checked true,
+	false or mixed, and its state in data-state (checked, unchecked,
+	indeterminate) and data-disabled. Pressing the box or anywhere on its row
+	(the label, the tag, the hint) toggles it; an indeterminate box becomes
+	checked. Inside a CheckboxGroup, give it a `value`. Attributes, handlers
+	and `class` go to the button.
+-->
+<div class="hp-checkbox">
+	<span class="control">
+		<BitsCheckbox.Root bind:checked bind:indeterminate bind:ref {id} aria-describedby={describedByIds} {...rest}>
+			{#snippet child({ props })}
+				<button {...props} class={['box', className]}>
+					<svg class="mark mixed" viewBox="0 0 12 12" aria-hidden="true"><path d="M2 6h8" /></svg>
+					<svg class="mark check" viewBox="0 0 12 12" aria-hidden="true"><path d="M1.5 6.5l3 3 6-6" /></svg>
+				</button>
+			{/snippet}
+		</BitsCheckbox.Root>
+	</span>
+	{#if label}
+		<label class="hp-dense" class:tagged={!!tag} for={id}
+			>{label}{#if tag}{' '}<Tag as="span">{tag}</Tag>{/if}</label
+		>
+	{/if}
+	{#if hint}
+		<p class="hint hp-caption" id={hintId}>{hint}</p>
+	{/if}
+</div>
+
+<style>
+	/* The box, then the label as written. The first line is one hit-target
+	   band (24px fine, 44px coarse): the box sits centred in it and the
+	   label's first line too, so a label that wraps keeps the box beside its
+	   first line. The hint runs under the label, aligned with its text.
+	   The root is as wide as its content (without a label, as the box), and
+	   with a label all of it is the target: the label's ::after covers the
+	   root, so a press on the hint, the tag or the space between them is a
+	   press on the label. The box sits above that cover with its own hit
+	   area. */
+	.hp-checkbox {
+		/* The label's line height, as .hp-dense sets it. */
+		--_line: 24px;
+		position: relative;
+		display: grid;
+		grid-template-columns: auto;
+		justify-content: start;
+		align-items: start;
+		width: fit-content;
+		max-width: 100%;
+	}
+	.hp-checkbox:has(> label) {
+		grid-template-columns: auto minmax(0, 1fr);
+		column-gap: var(--space-3);
+	}
+	@media (pointer: fine) {
+		.hp-checkbox {
+			--_line: 20px;
+		}
+	}
+
+	.control {
+		position: relative;
+		z-index: 1;
+		display: flex;
+		align-items: center;
+		height: var(--hit-target);
+	}
+
+	/* A black box with a 3:1 boundary. Checked or indeterminate, the edge and
+	   the mark turn titanium; the box stays black, because selection is never
+	   a fill. Focus is base.css's contour 4px outside, so it never looks like
+	   the checked edge. */
+	.box {
+		position: relative;
+		display: grid;
+		place-items: center;
+		box-sizing: border-box;
+		width: 20px;
+		height: 20px;
+		margin: 0;
+		padding: 0;
+		border: 1px solid var(--border-control);
+		background: var(--canvas);
+		color: var(--accent);
+		cursor: pointer;
+		-webkit-tap-highlight-color: transparent;
+	}
+	/* The hit area: at least --hit-target square, centred on the box. */
+	.box::before {
+		content: '';
+		position: absolute;
+		top: 50%;
+		left: 50%;
+		width: max(100%, var(--hit-target));
+		height: max(100%, var(--hit-target));
+		translate: -50% -50%;
+	}
+	.box[data-state='checked'],
+	.box[data-state='indeterminate'] {
+		border-color: var(--accent);
+	}
+
+	/* Both marks are always there, each at opacity 0 until its state comes.
+	   The mark a change brings fades in from 0 at its place over --dur-mark
+	   (BRIEF, short motion); the mark it takes away goes at once. A CSS
+	   transition never runs on an element's first style, so a box that
+	   renders checked or mixed shows its mark at once. 0ms is a snap.
+	   Opacity only: nothing moves, so reduced motion keeps it. */
+	.mark {
+		grid-area: 1 / 1;
+		width: 12px;
+		height: 12px;
+		fill: none;
+		stroke: currentColor;
+		stroke-width: 2px;
+		opacity: 0;
+	}
+	.box[data-state='indeterminate'] .mixed,
+	.box[data-state='checked'] .check {
+		opacity: 1;
+		transition: opacity var(--dur-mark) var(--settle);
+	}
+
+	label {
+		justify-self: start;
+		padding: calc((var(--hit-target) - var(--_line)) / 2) 0;
+		cursor: pointer;
+		-webkit-tap-highlight-color: transparent;
+	}
+	label::after {
+		content: '';
+		position: absolute;
+		inset: 0;
+	}
+	/* The tag sits after the label when both fit on one line; otherwise it
+	   wraps under the label whole. */
+	.tagged {
+		display: flex;
+		flex-wrap: wrap;
+		align-items: center;
+		gap: var(--space-1) var(--space-2);
+	}
+
+	/* Under the label's text; without a label, under the box. */
+	.hint {
+		grid-column: -2;
+		color: var(--muted);
+	}
+
+	/* ---- Hover: fine pointers only, over any part of the row ----------- */
+
+	@media (hover: hover) and (pointer: fine) {
+		.box {
+			transition:
+				background-color var(--dur-hover) var(--settle),
+				border-color var(--dur-hover) var(--settle);
+		}
+		.hp-checkbox:has(> label:hover, .box:hover) .box:not(:disabled) {
+			background-color: var(--surface-hover);
+		}
+		.hp-checkbox:has(> label:hover, .box:hover) .box[data-state='unchecked']:not(:disabled) {
+			border-color: var(--muted);
+		}
+		.hp-checkbox:has(> label:active, .box:active) .box:not(:disabled) {
+			transition-duration: var(--dur-press);
+		}
+	}
+
+	/* ---- Press: one step past hover, so it reads on a phone too -------- */
+
+	.hp-checkbox:has(> label:active, .box:active) .box:not(:disabled) {
+		background-color: var(--surface-raised);
+	}
+
+	/* ---- Disabled: the quieter --border and muted ink, the tag too ----- */
+
+	.box:disabled {
+		border-color: var(--border);
+		color: var(--muted);
+		cursor: not-allowed;
+	}
+	.hp-checkbox:has(.box:disabled) label {
+		color: var(--muted);
+		cursor: not-allowed;
+	}
+	.hp-checkbox:has(.box:disabled) label > :global(.hp-tag) {
+		background: var(--muted);
+	}
+</style>

package/dist/components/Checkbox.svelte.d.ts

@@ -0,0 +1,23 @@
+import { Checkbox as BitsCheckbox } from 'bits-ui';
+/** Attributes and handlers not listed here go to the checkbox button. */
+export type CheckboxProps = Omit<BitsCheckbox.RootProps, 'child' | 'children' | 'ref'> & {
+    /**
+     * The text beside the box, as written (never caps). Pressing it, or
+     * anywhere on the box's row, toggles the box. Without it, give the box
+     * an accessible name with `aria-label`.
+     */
+    label?: string;
+    /**
+     * A Tag after the label, such as "Recommended": a short fixed string the
+     * app defines, set in caps. It is part of the box's accessible name and
+     * shows only with a `label`.
+     */
+    tag?: string;
+    /** A second line in `--muted` under the label, read out as the box's description. */
+    hint?: string;
+    /** The checkbox button. */
+    ref?: HTMLElement | null;
+};
+declare const Checkbox: import("svelte").Component<CheckboxProps, {}, "ref" | "checked" | "indeterminate">;
+type Checkbox = ReturnType<typeof Checkbox>;
+export default Checkbox;