@nice2dev/ui-core 1.0.21 → 1.0.22

package/dist/core/tutorials.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Tutorial launcher — universal, decoupled "?" tutorial button + global toggle.
+ * @nice2dev/ui-core
+ *
+ * The rich overlay (`NiceTutorial`) lives in `@nice2dev/ui`. To let ANY package
+ * (even react-only ones) add a tutorial "?" button without importing the overlay,
+ * the launcher is split:
+ *  - this module (ui-core, lowest level): the `?` button, a context, the global
+ *    on/off flag, types and resolvers — no dependency on the overlay;
+ *  - `NiceTutorialHost` (in `@nice2dev/ui`): bridges this context to the real
+ *    `NiceTutorial`. The app mounts the host once; `enabled` comes from prefs
+ *    (e.g. an OmniVerk "hide all tutorials" preference).
+ *
+ * Editors expose an optional `tutorial?: NiceComponentTutorial` prop and render
+ * `<NiceTutorialButton steps={resolveTutorial(tutorial, BUILTIN_TOUR)} />`.
+ */
+import React from 'react';
+/** A tutorial step authored on a component (i18n-key aware). */
+export interface NiceTutorialStepDef {
+    /** CSS selector for the highlighted element (use stable `data-tour="…"`). */
+    target: string;
+    /** Inline English default (authoritative fallback). */
+    title?: string;
+    content?: string;
+    /** i18n keys resolved via `t(key, default)` at launch (locale-aware). */
+    titleKey?: string;
+    contentKey?: string;
+    placement?: 'top' | 'bottom' | 'left' | 'right' | 'auto';
+    highlightPadding?: number;
+    showArrow?: boolean;
+    scrollIntoView?: boolean;
+    disableInteraction?: boolean;
+}
+/** A fully-resolved step (structurally compatible with `NiceTutorialStep`). */
+export interface NiceResolvedTutorialStep {
+    target: string;
+    title: string;
+    content: string;
+    placement?: 'top' | 'bottom' | 'left' | 'right' | 'auto';
+    highlightPadding?: number;
+    showArrow?: boolean;
+    scrollIntoView?: boolean;
+    disableInteraction?: boolean;
+}
+/**
+ * The optional `tutorial?` prop shape used across editors:
+ *  - `true` → use the component's built-in tour;
+ *  - `NiceTutorialStepDef[]` → custom steps;
+ *  - `{ steps?, autoStart?, label? }` → custom steps (fallback to built-in) + options;
+ *  - `false`/omitted → no "?" button.
+ */
+export type NiceComponentTutorial = boolean | NiceTutorialStepDef[] | {
+    steps?: NiceTutorialStepDef[];
+    autoStart?: boolean;
+    label?: string;
+};
+export interface NiceTutorialsContextValue {
+    /** Global on/off — when false, all `NiceTutorialButton`s render nothing. */
+    enabled: boolean;
+    /** Whether a tutorial is currently running (host-driven). */
+    active: boolean;
+    /** Launch resolved steps (wired by `NiceTutorialHost`; no-op without a host). */
+    run: (steps: NiceResolvedTutorialStep[], opts?: {
+        autoStart?: boolean;
+    }) => void;
+}
+export interface NiceTutorialsProviderProps {
+    /** Global enable flag (default `true`). Set `false` to hide every "?" button. */
+    enabled?: boolean;
+    /** Whether a tutorial is active (host-driven). */
+    active?: boolean;
+    /** Launcher implementation (provided by `NiceTutorialHost`). */
+    onRun?: (steps: NiceResolvedTutorialStep[], opts?: {
+        autoStart?: boolean;
+    }) => void;
+    children: React.ReactNode;
+}
+export declare const NiceTutorialsProvider: React.FC<NiceTutorialsProviderProps>;
+/** Access the tutorials context (`enabled`, `active`, `run`). */
+export declare function useNiceTutorials(): NiceTutorialsContextValue;
+/** Convenience: whether tutorial "?" buttons should be shown globally. */
+export declare function useNiceTutorialsEnabled(): boolean;
+/** Normalise a `tutorial?` prop value (+ component built-in) to steps or null. */
+export declare function resolveTutorial(tutorial: NiceComponentTutorial | undefined, builtin?: NiceTutorialStepDef[]): NiceTutorialStepDef[] | null;
+/** Resolve i18n-key titles/content to strings using a `t(key, default)` fn. */
+export declare function resolveStepsI18n(steps: NiceTutorialStepDef[], t: (key: string, defaultValue: string) => string): NiceResolvedTutorialStep[];
+export interface NiceTutorialButtonProps {
+    /** Steps to run (already normalised via {@link resolveTutorial}). */
+    steps?: NiceTutorialStepDef[] | null;
+    /** Auto-start option forwarded to `run`. */
+    autoStart?: boolean;
+    /** Accessible label / tooltip. Defaults to the i18n `tutorial.startAria`. */
+    label?: string;
+    /** Size. Default `'md'`. */
+    size?: 'sm' | 'md';
+    className?: string;
+    style?: React.CSSProperties;
+    'data-testid'?: string;
+}
+/**
+ * Small "?" button that launches a tutorial. Renders nothing when tutorials are
+ * globally disabled or no steps are provided — so it's safe to render
+ * unconditionally as `<NiceTutorialButton steps={resolveTutorial(...)} />`.
+ */
+export declare const NiceTutorialButton: React.FC<NiceTutorialButtonProps>;
+//# sourceMappingURL=tutorials.d.ts.map

package/dist/core/tutorials.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tutorials.d.ts","sourceRoot":"","sources":["../../src/core/tutorials.tsx"],"names":[],"mappings":"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"}