@spinjs/components 0.0.0-stage → 0.1.0-preview.1

package/dist/tour/examples/basic.html

@@ -0,0 +1,67 @@
+<script lang="ts">
+import { tour } from "../tour.presentation.js";
+
+const machine = tour({
+  label: "Tour",
+  steps:
+    '[{"id":"welcome","target":"#tour-basic-target","title":"Welcome","description":"This button starts nothing, but the spotlight finds it."},{"id":"confirm","target":"#tour-basic-confirm","title":"Confirm","description":"The spotlight follows to the next target."},{"id":"done","title":"Done","description":"No target — the card stands alone."}]',
+});
+</script>
+
+<div class="mx-auto flex w-full max-w-[20rem] flex-col items-center gap-4">
+  <button id="tour-basic-target"
+    class="secondary s-sm">Feature button</button>
+  <button id="tour-basic-confirm"
+    class="secondary s-sm">Confirm button</button>
+  <button
+    class="s-sm"
+    {...machine.getStartTriggerProps()}>Start tour</button>
+</div>
+<div class="contents" {...machine.getRootProps()}>
+  <div
+    show={machine.active}
+    class="pointer-events-none fixed inset-0 z-modal bg-surface-sunken opacity-70 transition-opacity duration-fast ease-decelerate"
+    {...machine.getBackdropProps()}></div>
+
+  <div
+    show={machine.active}
+    class="pointer-events-none fixed z-modal rounded-lg ring-2 ring-primary transition-all duration-fast ease-decelerate"
+    {...machine.getSpotlightProps()}></div>
+
+  <div
+    class={["fixed z-modal w-[min(20rem,90vw)] rounded-lg border border-solid border-border bg-surface-raised p-3 shadow-lg transition-opacity duration-fast ease-decelerate", { "pointer-events-none invisible opacity-0": !machine.active }]}
+    {...machine.getPositionerProps()}>
+    <div class="flex flex-col gap-2" {...machine.getContentProps()}>
+      <template for={machine.getTextRows()} as={row} key={row.key}>
+        <div class="flex items-center justify-between gap-2">
+          <span class="text-sm font-medium text-text"
+            {...machine.getTitleProps()}>{row.title}</span>
+          <span class="text-xs text-text-muted tabular-nums"
+            {...machine.getProgressTextProps()}>{row.progress}</span>
+        </div>
+        <p class="text-xs text-text-muted"
+          {...machine.getDescriptionProps()}>{row.description}</p>
+      </template>
+      <div class="flex items-center justify-between gap-2">
+        <div class="flex items-center gap-1">
+          <button
+            class="ghost s-sm"
+            {...machine.getPrevTriggerProps()}>Back</button>
+          <button
+            class="s-sm"
+            {...machine.getNextTriggerProps()}>Next</button>
+        </div>
+        <div class="flex items-center gap-1">
+          <button
+            class="ghost s-sm"
+            {...machine.getSkipTriggerProps()}>Skip</button>
+          <button
+            class="ghost icon s-sm"
+            {...machine.getDismissTriggerProps()}>
+            <span class="i-lucide-x text-xs" aria-hidden="true"></span>
+          </button>
+        </div>
+      </div>
+    </div>
+  </div>
+</div>

package/dist/tour/tour.events.d.ts

@@ -0,0 +1,32 @@
+import { EventUnion } from "@spinjs/runtime/fsm";
+export interface TourEvents {
+  "START": {};
+  "STEP.SET": {
+    step: number;
+  };
+  "STEP.NEXT": {};
+  "STEP.PREV": {};
+  "TARGET.RESOLVED": {};
+  "TARGET.NOT_FOUND": {};
+  "SCROLL.END": {};
+  /** The resolved target's box: the spotlight's geometry, measured by the
+   * view and handed to the machine, which owns it. */
+  "SPOTLIGHT.SET": {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+  };
+  "DISMISS": {};
+  "SKIP": {};
+}
+export type TourEvent = EventUnion<TourEvents>;
+export type TourStepChange = {
+  readonly step: number;
+  readonly stepId: string;
+};
+export type TourDismissChange = {
+  readonly reason: "complete" | "dismiss" | "skip" | "not-found";
+  readonly step: number;
+};
+//# sourceMappingURL=tour.events.d.ts.map

package/dist/tour/tour.events.js

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

package/dist/tour/tour.machine.d.ts

@@ -0,0 +1,5 @@
+import { TourArgs, TourContext, TourState } from "./tour.state.js";
+import { TourEvents } from "./tour.events.js";
+import { Machine } from "@spinjs/runtime/fsm";
+export declare function tour(args?: TourArgs, authored?: (name: string) => boolean): Machine<TourContext, TourEvents, TourState>;
+//# sourceMappingURL=tour.machine.d.ts.map

package/dist/tour/tour.machine.js

@@ -0,0 +1,77 @@
+import { initial } from "./tour.state.js";
+import { bail, hasNext, hasPrev, hasSteps, nextStep, prevStep, setSpotlight, setStep, startTour, validStep } from "./tour.transitions.js";
+import { createMachine } from "@spinjs/runtime/fsm";
+// src/tour/tour.machine.ts
+/**
+* Tour machine: the inactive and running modes, and the three phases a
+* running step passes through — a step resolves its target, scrolls it
+* into view, then shows its spotlight.
+*/
+function tour(args = {}, authored = () => true) {
+	return createMachine({
+		id: "tour",
+		initial: "inactive",
+		context: initial(args, authored),
+		fields: {
+			step: { event: "STEP.SET" },
+			disabled: {},
+			spotlightPadding: {},
+			label: {}
+		},
+		on: {
+			"SPOTLIGHT.SET": { assign: setSpotlight },
+			"STEP.SET": [{
+				cond: validStep,
+				target: "resolving",
+				assign: setStep
+			}]
+		},
+		states: {
+			inactive: { on: { "START": [{
+				cond: hasSteps,
+				target: "resolving",
+				assign: startTour
+			}] } },
+			resolving: { on: {
+				"TARGET.NOT_FOUND": [{
+					target: "inactive",
+					assign: bail
+				}],
+				"TARGET.RESOLVED": [{ target: "scrolling" }],
+				"DISMISS": [{
+					target: "inactive",
+					assign: bail
+				}],
+				"SKIP": [{ target: "inactive" }]
+			} },
+			scrolling: { on: {
+				"SCROLL.END": [{ target: "active" }],
+				"DISMISS": [{
+					target: "inactive",
+					assign: bail
+				}],
+				"SKIP": [{ target: "inactive" }]
+			} },
+			active: { on: {
+				"STEP.NEXT": [{
+					cond: hasNext,
+					target: "resolving",
+					assign: nextStep
+				}],
+				"STEP.PREV": [{
+					cond: hasPrev,
+					target: "resolving",
+					assign: prevStep
+				}],
+				"DISMISS": [{
+					target: "inactive",
+					assign: bail
+				}],
+				"SKIP": [{ target: "inactive" }]
+			} }
+		}
+	});
+}
+export { tour };
+
+//# sourceMappingURL=tour.machine.js.map

package/dist/tour/tour.presentation.d.ts

@@ -0,0 +1,260 @@
+import { TourArgs, TourContext, TourState, TourStepRecord } from "./tour.state.js";
+import { TourDismissChange, TourEvents, TourStepChange } from "./tour.events.js";
+import { ApiOf, ViewFor } from "@spinjs/runtime";
+/**
+ * Tour definition: the DOM contract as data. The machine owns the modes
+ * (inactive/resolving/scrolling/active) and the step index; this file maps
+ * props to channels, parts to attribute bags, and commands to sends.
+ */
+type ScopeLike = ViewFor<TourContext, TourEvents, TourState>;
+export declare const def: {
+  name: string;
+  machine: (args: TourArgs, authored: (name: string) => boolean) => import("@spinjs/runtime").Machine<TourContext, TourEvents, TourState>;
+  start: "inactive";
+  settled: ({ event, after, props, send }: {
+    readonly event: import("@spinjs/runtime").AnyEvent;
+    readonly before: {
+      readonly context: TourContext;
+      readonly state: TourState;
+    };
+    readonly after: {
+      readonly context: TourContext;
+      readonly state: TourState;
+    };
+    readonly props: Record<string, unknown>;
+    readonly root: () => Element;
+    readonly id: (part: string, slot?: unknown) => string;
+    readonly focus: (part: string, slot?: unknown) => void;
+    readonly measure: (part: string, slot?: unknown) => DOMRect | null;
+    readonly send: (event: import("@spinjs/runtime").AnyEvent) => void;
+  }) => void;
+  parts: {
+    root: {
+      attrs: (scope: ScopeLike) => {
+        "data-state": string;
+      };
+    };
+    backdrop: {
+      attrs: (scope: ScopeLike) => {
+        "data-state": string;
+      };
+    };
+    spotlight: {
+      attrs: (scope: ScopeLike) => {
+        "data-state": string;
+        hidden: boolean;
+        style: {
+          left: string;
+          top: string;
+          width: string;
+          height: string;
+        };
+      };
+    };
+    positioner: {
+      attrs: (scope: ScopeLike) => {
+        "data-state": string;
+        style: {
+          left: string;
+          top: string;
+        };
+        "use:dismissable": {
+          onOutside: () => void;
+          onEscape: () => void;
+        };
+      };
+    };
+    content: {
+      attrs: (scope: ScopeLike) => {
+        role: string;
+        "aria-label": string;
+        "data-state": string;
+        hidden: boolean;
+      };
+    };
+    title: {
+      attrs: (_scope: ScopeLike) => {};
+    };
+    description: {
+      attrs: (_scope: ScopeLike) => {};
+    };
+    progressText: {
+      id: string;
+      attrs: (scope: ScopeLike) => {
+        text: string;
+      };
+    };
+    startTrigger: {
+      id: string;
+      attrs: (scope: ScopeLike) => {
+        "aria-label": string;
+        onClick: () => void;
+      };
+    };
+    prevTrigger: {
+      id: string;
+      attrs: (scope: ScopeLike) => {
+        "aria-label": string;
+        hidden: boolean;
+        onClick: () => void;
+      };
+    };
+    nextTrigger: {
+      id: string;
+      attrs: (scope: ScopeLike) => {
+        "aria-label": string;
+        onClick: () => void;
+      };
+    };
+    dismissTrigger: {
+      id: string;
+      attrs: (scope: ScopeLike) => {
+        "aria-label": string;
+        onClick: () => void;
+      };
+    };
+    skipTrigger: {
+      id: string;
+      attrs: (scope: ScopeLike) => {
+        "aria-label": string;
+        onClick: () => void;
+      };
+    };
+  };
+  commands: {
+    start: {
+      event: () => {
+        type: "START";
+      };
+    };
+    next: {
+      event: () => {
+        type: "STEP.NEXT";
+      };
+    };
+    prev: {
+      event: () => {
+        type: "STEP.PREV";
+      };
+    };
+    dismiss: {
+      event: () => {
+        type: "DISMISS";
+      };
+    };
+    skip: {
+      event: () => {
+        type: "SKIP";
+      };
+    };
+    setStep: {
+      event: ([step]: [step: number]) => {
+        type: "STEP.SET";
+        step: number;
+      };
+    };
+    notifyTargetResolved: {
+      event: () => {
+        type: "TARGET.RESOLVED";
+      };
+    };
+    notifyTargetNotFound: {
+      event: () => {
+        type: "TARGET.NOT_FOUND";
+      };
+    };
+    notifyScrollEnd: {
+      event: () => {
+        type: "SCROLL.END";
+      };
+    };
+  };
+  readers: {
+    step: {
+      read: (context: TourContext) => number;
+    };
+    steps: {
+      read: (context: TourContext) => readonly TourStepRecord[];
+    };
+    running: {
+      read: (_context: TourContext, state: TourState) => boolean;
+    };
+    active: {
+      read: (_context: TourContext, state: TourState) => state is "active";
+    };
+    state: {
+      read: (_context: TourContext, state: TourState) => TourState;
+    };
+  };
+  methods: {
+    getTextRows: {
+      call: (context: TourContext) => {
+        key: string;
+        readonly title: string;
+        readonly description: string;
+        readonly progress: string;
+      }[];
+    };
+  };
+  events: {
+    start: {
+      prop: string;
+      watch: () => never[];
+      detail: () => {
+        step: number;
+      };
+      select: (event: {
+        readonly type: string;
+      } & Record<string, unknown>, _before: TourContext, after: TourContext, states: {
+        readonly was: string;
+        readonly is: string;
+      } | undefined) => {
+        step: number;
+      } | null;
+    };
+    "step-change": {
+      prop: string;
+      watch: () => never[];
+      detail: () => {
+        step: number;
+      };
+      select: (event: {
+        readonly type: string;
+      } & Record<string, unknown>, before: TourContext, after: TourContext) => {
+        step: number;
+        stepId: string;
+      } | null;
+    };
+    dismiss: {
+      prop: string;
+      watch: () => never[];
+      detail: () => {
+        reason: string;
+      };
+      select: (event: {
+        readonly type: string;
+      } & Record<string, unknown>, before: TourContext, after: TourContext, states: {
+        readonly was: string;
+        readonly is: string;
+      } | undefined) => {
+        reason: string;
+        step: number;
+      } | null;
+    };
+    complete: {
+      prop: string;
+      watch: () => never[];
+      detail: () => {};
+      select: (event: {
+        readonly type: string;
+      } & Record<string, unknown>, before: TourContext, after: TourContext, states: {
+        readonly was: string;
+        readonly is: string;
+      } | undefined) => {} | null;
+    };
+  };
+};
+export type TourApi = ApiOf<typeof def>;
+export declare const tour: import("@spinjs/runtime").DefinedComponent<TourApi, TourArgs>;
+export type { TourArgs, TourDismissChange, TourState, TourStepChange, TourStepRecord };
+//# sourceMappingURL=tour.presentation.d.ts.map