@thelol3882/sapar 0.0.0-stage → 0.3.0

package/templates/mantine/AnnouncementModal.tsx

@@ -0,0 +1,66 @@
+'use client';
+
+// After copying, change these imports to '@thelol3882/sapar/...'
+import { Anchor, Button, Group, Image, Modal, Stack, Text } from '@mantine/core';
+import { useAnnouncementInterruption, useWhatsNew } from '../../src/react';
+
+export interface AnnouncementModalLabels {
+    acknowledge: string;
+    takeTour: string;
+}
+
+const DEFAULT_LABELS: AnnouncementModalLabels = {
+    acknowledge: 'Got it',
+    takeTour: 'Take the tour',
+};
+
+export function AnnouncementModal({ labels }: { labels?: Partial<AnnouncementModalLabels> }) {
+    const text = { ...DEFAULT_LABELS, ...labels };
+    const { announcement, dismiss, acknowledge } = useAnnouncementInterruption();
+    const { recordClick, startTour } = useWhatsNew();
+
+    if (!announcement) return null;
+    const { tourKey } = announcement;
+
+    async function takeTour(tourKey: string): Promise<void> {
+        await acknowledge();
+        await startTour(tourKey);
+    }
+
+    return (
+        <Modal
+            opened
+            centered
+            withCloseButton={false}
+            title={announcement.title}
+            onClose={() => void dismiss()}
+        >
+            <Stack gap="sm">
+                {announcement.imageUrl && <Image src={announcement.imageUrl} alt="" radius="md" />}
+                <Text size="sm" c="dimmed">
+                    {announcement.body}
+                </Text>
+                {announcement.cta && (
+                    <Anchor
+                        href={announcement.cta.url}
+                        target="_blank"
+                        rel="noreferrer"
+                        size="sm"
+                        fw={500}
+                        onClick={() => recordClick(announcement.key)}
+                    >
+                        {announcement.cta.label}
+                    </Anchor>
+                )}
+                <Group justify="flex-end" mt="xs">
+                    {tourKey && (
+                        <Button variant="subtle" color="gray" onClick={() => void takeTour(tourKey)}>
+                            {text.takeTour}
+                        </Button>
+                    )}
+                    <Button onClick={() => void acknowledge()}>{text.acknowledge}</Button>
+                </Group>
+            </Stack>
+        </Modal>
+    );
+}

package/templates/mantine/TourCard.tsx

@@ -0,0 +1,84 @@
+'use client';
+
+// After copying, change these imports to '@thelol3882/sapar/...'
+import { Button, CloseButton, Group, Paper, Text, Title } from '@mantine/core';
+import type { CSSProperties } from 'react';
+import { TourOverlay, TourStep, type TourOverlayProps } from '../../src/web';
+import type { StepAnnouncement, StepCount } from '../../src/react';
+
+export interface TourCardLabels {
+    next: string;
+    back: string;
+    skip: string;
+    done: string;
+    close: string;
+    progress: ({ position, total }: StepCount) => string;
+    announceStep: ({ position, total, title }: StepAnnouncement) => string;
+}
+
+const DEFAULT_LABELS: TourCardLabels = {
+    next: 'Next',
+    back: 'Back',
+    skip: 'Skip tour',
+    done: 'Done',
+    close: 'Close tour',
+    progress: ({ position, total }) => `${position} / ${total}`,
+    announceStep: ({ position, total, title }) => `Step ${position} of ${total}: ${title}`,
+};
+
+const SPOTLIGHT_STYLE: CSSProperties = {
+    zIndex: 'var(--mantine-z-index-overlay)',
+    color: 'color-mix(in srgb, var(--mantine-color-black) 50%, transparent)',
+};
+
+const POPOVER_STYLE: CSSProperties = { zIndex: 'calc(var(--mantine-z-index-overlay) + 1)' };
+
+export interface TourCardProps extends Pick<TourOverlayProps, 'presentation'> {
+    labels?: Partial<TourCardLabels>;
+}
+
+export function TourCard({ labels, presentation }: TourCardProps) {
+    const text = { ...DEFAULT_LABELS, ...labels };
+
+    return (
+        <TourOverlay spotlightStyle={SPOTLIGHT_STYLE} popoverStyle={POPOVER_STYLE} presentation={presentation}>
+            <Paper
+                withBorder
+                shadow="md"
+                radius="md"
+                p="md"
+                w={320}
+                maw="calc(100vw - 2rem)"
+                className="mantine-focus-auto"
+                renderRoot={(props) => <TourStep.Root {...props} announceStep={text.announceStep} />}
+            >
+                <Group justify="space-between" mb="xs">
+                    <Text
+                        size="xs"
+                        fw={500}
+                        c="dimmed"
+                        renderRoot={(props) => <TourStep.Progress {...props}>{text.progress}</TourStep.Progress>}
+                    />
+                    <TourStep.Close aria-label={text.close} render={({ children: _icon, ...props }) => <CloseButton {...props} />} />
+                </Group>
+                <Title order={5} renderRoot={(props) => <TourStep.Title {...props} />} />
+                <Text size="sm" c="dimmed" mt={4} renderRoot={(props) => <TourStep.Body {...props} />} />
+                <Group justify="space-between" mt="md">
+                    <TourStep.Skip render={(props) => <Button variant="subtle" color="gray" size="xs" {...props} />}>
+                        {text.skip}
+                    </TourStep.Skip>
+                    <Group gap="xs">
+                        <TourStep.Back render={(props) => <Button variant="subtle" color="gray" size="xs" {...props} />}>
+                            {text.back}
+                        </TourStep.Back>
+                        <TourStep.Next
+                            nextLabel={text.next}
+                            doneLabel={text.done}
+                            render={(props) => <Button size="xs" {...props} />}
+                        />
+                    </Group>
+                </Group>
+            </Paper>
+        </TourOverlay>
+    );
+}

package/templates/mantine/WhatsNewButton.tsx

@@ -0,0 +1,62 @@
+'use client';
+
+// After copying, change these imports to '@thelol3882/sapar/...'
+import { ActionIcon, Indicator } from '@mantine/core';
+import { useState } from 'react';
+import { useWhatsNew } from '../../src/react';
+import { WhatsNewPanel, type WhatsNewPanelProps } from './WhatsNewPanel';
+
+const MAX_DISPLAYED_COUNT = 9;
+
+export interface WhatsNewButtonProps extends Pick<WhatsNewPanelProps, 'labels' | 'locale' | 'formatDate'> {
+    className?: string;
+    /** Accessible name; the unread count is appended. */
+    label?: string;
+}
+
+function SparkleIcon() {
+    return (
+        <svg
+            viewBox="0 0 24 24"
+            fill="none"
+            stroke="currentColor"
+            strokeWidth="2"
+            strokeLinecap="round"
+            strokeLinejoin="round"
+            width="20"
+            height="20"
+            aria-hidden="true"
+        >
+            <path d="M9.9 15.5a2 2 0 0 0-1.4-1.4l-6.1-1.6a.5.5 0 0 1 0-1l6.1-1.6a2 2 0 0 0 1.4-1.4l1.6-6.1a.5.5 0 0 1 1 0l1.6 6.1a2 2 0 0 0 1.4 1.4l6.1 1.6a.5.5 0 0 1 0 1l-6.1 1.6a2 2 0 0 0-1.4 1.4l-1.6 6.1a.5.5 0 0 1-1 0zM20 3v4M22 5h-4M4 17v2M5 18H3" />
+        </svg>
+    );
+}
+
+export function WhatsNewButton({ className, label = "What's new", labels, locale, formatDate }: WhatsNewButtonProps) {
+    const [open, setOpen] = useState(false);
+    const { unreadCount } = useWhatsNew();
+
+    return (
+        <>
+            <Indicator
+                label={unreadCount > MAX_DISPLAYED_COUNT ? `${MAX_DISPLAYED_COUNT}+` : unreadCount}
+                disabled={unreadCount === 0}
+                size={16}
+                color="red"
+            >
+                <ActionIcon
+                    variant="subtle"
+                    color="gray"
+                    size="lg"
+                    radius="xl"
+                    className={className}
+                    aria-label={unreadCount > 0 ? `${label} (${unreadCount})` : label}
+                    onClick={() => setOpen(true)}
+                >
+                    <SparkleIcon />
+                </ActionIcon>
+            </Indicator>
+            <WhatsNewPanel open={open} onClose={() => setOpen(false)} labels={labels} locale={locale} formatDate={formatDate} />
+        </>
+    );
+}

package/templates/mantine/WhatsNewPanel.tsx

@@ -0,0 +1,129 @@
+'use client';
+
+// After copying, change these imports to '@thelol3882/sapar/...'
+import { Anchor, Badge, Button, Drawer, Group, Image, ScrollArea, Stack, Text, Title } from '@mantine/core';
+import { useWhatsNewPanel, type WhatsNewPanelItem } from '../../src/react';
+
+export interface WhatsNewPanelLabels {
+    title: string;
+    empty: string;
+    close: string;
+    takeTour: string;
+    new: string;
+}
+
+const DEFAULT_LABELS: WhatsNewPanelLabels = {
+    title: "What's new",
+    empty: 'Nothing new yet.',
+    close: 'Close',
+    takeTour: 'Take the tour',
+    new: 'New',
+};
+
+export interface WhatsNewPanelProps {
+    open: boolean;
+    onClose: () => void;
+    labels?: Partial<WhatsNewPanelLabels>;
+    /** BCP 47 tag for the default date format. Defaults to the browser locale. */
+    locale?: string;
+    /** Replaces the default date format; the template then never uses `Intl`. */
+    formatDate?: (isoDate: string) => string;
+}
+
+function formatDateWithIntl(isoDate: string, locale: string | undefined): string {
+    return new Intl.DateTimeFormat(locale, { dateStyle: 'medium' }).format(new Date(isoDate));
+}
+
+function Entry({
+    item,
+    labels,
+    formatDate,
+    onCtaClick,
+    onTakeTour,
+}: {
+    item: WhatsNewPanelItem;
+    labels: WhatsNewPanelLabels;
+    formatDate: (isoDate: string) => string;
+    onCtaClick: (key: string) => void;
+    onTakeTour: (tourKey: string) => void;
+}) {
+    const { tourKey } = item;
+
+    return (
+        <Stack component="li" gap="xs">
+            <Group gap="xs">
+                <Title order={4}>{item.title}</Title>
+                {item.isNew && <Badge size="sm">{labels.new}</Badge>}
+            </Group>
+            {item.publishedAt && (
+                <Text component="time" dateTime={item.publishedAt} size="xs" c="dimmed">
+                    {formatDate(item.publishedAt)}
+                </Text>
+            )}
+            {item.imageUrl && <Image src={item.imageUrl} alt="" loading="lazy" radius="md" />}
+            <Text size="sm" c="dimmed">
+                {item.body}
+            </Text>
+            <Group gap="md">
+                {tourKey && (
+                    <Button size="xs" onClick={() => onTakeTour(tourKey)}>
+                        {labels.takeTour}
+                    </Button>
+                )}
+                {item.cta && (
+                    <Anchor
+                        href={item.cta.url}
+                        target="_blank"
+                        rel="noreferrer"
+                        size="sm"
+                        fw={500}
+                        onClick={() => onCtaClick(item.key)}
+                    >
+                        {item.cta.label}
+                    </Anchor>
+                )}
+            </Group>
+        </Stack>
+    );
+}
+
+export function WhatsNewPanel({ open, onClose, labels, locale, formatDate }: WhatsNewPanelProps) {
+    const text = { ...DEFAULT_LABELS, ...labels };
+    const { items, recordClick, startTour } = useWhatsNewPanel(open);
+    const format = formatDate ?? ((isoDate: string) => formatDateWithIntl(isoDate, locale));
+
+    function takeTour(tourKey: string): void {
+        onClose();
+        void startTour(tourKey);
+    }
+
+    return (
+        <Drawer
+            opened={open}
+            onClose={onClose}
+            position="right"
+            title={text.title}
+            closeButtonProps={{ 'aria-label': text.close }}
+            scrollAreaComponent={ScrollArea.Autosize}
+        >
+            {items.length === 0 ? (
+                <Text size="sm" c="dimmed">
+                    {text.empty}
+                </Text>
+            ) : (
+                <Stack component="ul" gap="xl" p={0} m={0} style={{ listStyle: 'none' }}>
+                    {items.map((item) => (
+                        <Entry
+                            key={item.key}
+                            item={item}
+                            labels={text}
+                            formatDate={format}
+                            onCtaClick={recordClick}
+                            onTakeTour={takeTour}
+                        />
+                    ))}
+                </Stack>
+            )}
+        </Drawer>
+    );
+}

package/templates/tailwind/AnnouncementModal.tsx

@@ -0,0 +1,100 @@
+'use client';
+
+// After copying, change these imports to '@thelol3882/sapar/...'
+import { useEffect, useRef, type KeyboardEvent } from 'react';
+import { useAnnouncementInterruption, useWhatsNew } from '../../src/react';
+import { BodyPortal } from '../../src/web';
+
+export interface AnnouncementModalLabels {
+    acknowledge: string;
+    takeTour: string;
+}
+
+const DEFAULT_LABELS: AnnouncementModalLabels = {
+    acknowledge: 'Got it',
+    takeTour: 'Take the tour',
+};
+
+// Replace these with your design tokens.
+const styles = {
+    overlay: 'fixed inset-0 z-[900] flex items-center justify-center p-4',
+    backdrop: 'absolute inset-0 bg-black/50',
+    dialog: 'relative w-full max-w-md space-y-3 rounded-xl bg-white p-6 text-neutral-900 shadow-xl focus:outline-none dark:bg-neutral-900 dark:text-neutral-100',
+    image: 'w-full rounded-lg',
+    title: 'text-lg font-semibold',
+    body: 'text-sm text-neutral-600 dark:text-neutral-300',
+    link: 'inline-block text-sm font-medium text-indigo-600 hover:underline dark:text-indigo-400',
+    actions: 'flex justify-end gap-2 pt-2',
+    secondaryButton: 'rounded-lg px-3 py-1.5 text-sm font-medium text-neutral-700 hover:bg-neutral-100 dark:text-neutral-200 dark:hover:bg-neutral-800',
+    primaryButton: 'rounded-lg bg-indigo-600 px-3 py-1.5 text-sm font-medium text-white hover:bg-indigo-500',
+};
+
+export function AnnouncementModal({ labels }: { labels?: Partial<AnnouncementModalLabels> }) {
+    const text = { ...DEFAULT_LABELS, ...labels };
+    const { announcement, dismiss, acknowledge } = useAnnouncementInterruption();
+    const { recordClick, startTour } = useWhatsNew();
+    const dialogRef = useRef<HTMLDivElement>(null);
+    const announcementKey = announcement?.key;
+
+    useEffect(() => {
+        if (announcementKey) dialogRef.current?.focus();
+    }, [announcementKey]);
+
+    if (!announcement) return null;
+    const { tourKey } = announcement;
+
+    function handleKeyDown(event: KeyboardEvent): void {
+        if (event.key === 'Escape') void dismiss();
+    }
+
+    async function takeTour(tourKey: string): Promise<void> {
+        await acknowledge();
+        await startTour(tourKey);
+    }
+
+    return (
+        <BodyPortal>
+            <div className={styles.overlay} onKeyDown={handleKeyDown}>
+                <div className={styles.backdrop} aria-hidden="true" onClick={() => void dismiss()} />
+                <div
+                    ref={dialogRef}
+                    role="dialog"
+                    aria-modal="true"
+                    aria-labelledby="announcement-title"
+                    aria-describedby="announcement-body"
+                    tabIndex={-1}
+                    className={styles.dialog}
+                >
+                    {announcement.imageUrl && <img src={announcement.imageUrl} alt="" className={styles.image} />}
+                    <h2 id="announcement-title" className={styles.title}>
+                        {announcement.title}
+                    </h2>
+                    <p id="announcement-body" className={styles.body}>
+                        {announcement.body}
+                    </p>
+                    {announcement.cta && (
+                        <a
+                            href={announcement.cta.url}
+                            target="_blank"
+                            rel="noreferrer"
+                            onClick={() => recordClick(announcement.key)}
+                            className={styles.link}
+                        >
+                            {announcement.cta.label}
+                        </a>
+                    )}
+                    <div className={styles.actions}>
+                        {tourKey && (
+                            <button type="button" onClick={() => void takeTour(tourKey)} className={styles.secondaryButton}>
+                                {text.takeTour}
+                            </button>
+                        )}
+                        <button type="button" onClick={() => void acknowledge()} className={styles.primaryButton}>
+                            {text.acknowledge}
+                        </button>
+                    </div>
+                </div>
+            </div>
+        </BodyPortal>
+    );
+}

package/templates/tailwind/TourCard.tsx

@@ -0,0 +1,69 @@
+'use client';
+
+// After copying, change these imports to '@thelol3882/sapar/...'
+import { TourOverlay, TourStep, type TourOverlayProps } from '../../src/web';
+import type { StepAnnouncement, StepCount } from '../../src/react';
+
+export interface TourCardLabels {
+    next: string;
+    back: string;
+    skip: string;
+    done: string;
+    close: string;
+    progress: ({ position, total }: StepCount) => string;
+    announceStep: ({ position, total, title }: StepAnnouncement) => string;
+}
+
+const DEFAULT_LABELS: TourCardLabels = {
+    next: 'Next',
+    back: 'Back',
+    skip: 'Skip tour',
+    done: 'Done',
+    close: 'Close tour',
+    progress: ({ position, total }) => `${position} / ${total}`,
+    announceStep: ({ position, total, title }) => `Step ${position} of ${total}: ${title}`,
+};
+
+// Replace these with your design tokens.
+const styles = {
+    spotlight: 'z-[1000] text-black/50',
+    popover: 'z-[1001]',
+    card: 'w-80 max-w-[calc(100vw-2rem)] rounded-xl border border-neutral-200 bg-white p-4 text-neutral-900 shadow-xl outline-none focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-indigo-500 focus-visible:ring-offset-2 dark:border-neutral-700 dark:bg-neutral-900 dark:text-neutral-100 dark:focus-visible:ring-offset-neutral-900',
+    header: 'flex items-center justify-between',
+    progress: 'text-xs font-medium text-neutral-500 dark:text-neutral-400',
+    close: '-mr-1 rounded-md px-2 text-lg leading-none text-neutral-500 hover:bg-neutral-100 focus-visible:outline-2 focus-visible:outline-indigo-500 dark:hover:bg-neutral-800',
+    title: 'mt-2 text-base font-semibold',
+    body: 'mt-1 text-sm text-neutral-600 dark:text-neutral-300',
+    footer: 'mt-4 flex items-center justify-between gap-2',
+    actions: 'flex items-center gap-2',
+    secondaryButton: 'rounded-lg px-3 py-1.5 text-sm font-medium text-neutral-600 hover:bg-neutral-100 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-indigo-500 dark:text-neutral-300 dark:hover:bg-neutral-800',
+    primaryButton: 'rounded-lg bg-indigo-600 px-3 py-1.5 text-sm font-medium text-white hover:bg-indigo-500 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-indigo-500',
+};
+
+export interface TourCardProps extends Pick<TourOverlayProps, 'presentation'> {
+    labels?: Partial<TourCardLabels>;
+}
+
+export function TourCard({ labels, presentation }: TourCardProps) {
+    const text = { ...DEFAULT_LABELS, ...labels };
+
+    return (
+        <TourOverlay spotlightClassName={styles.spotlight} popoverClassName={styles.popover} presentation={presentation}>
+            <TourStep.Root announceStep={text.announceStep} className={styles.card}>
+                <div className={styles.header}>
+                    <TourStep.Progress className={styles.progress}>{text.progress}</TourStep.Progress>
+                    <TourStep.Close aria-label={text.close} className={styles.close} />
+                </div>
+                <TourStep.Title className={styles.title} />
+                <TourStep.Body className={styles.body} />
+                <div className={styles.footer}>
+                    <TourStep.Skip className={styles.secondaryButton}>{text.skip}</TourStep.Skip>
+                    <div className={styles.actions}>
+                        <TourStep.Back className={styles.secondaryButton}>{text.back}</TourStep.Back>
+                        <TourStep.Next nextLabel={text.next} doneLabel={text.done} className={styles.primaryButton} />
+                    </div>
+                </div>
+            </TourStep.Root>
+        </TourOverlay>
+    );
+}

package/templates/tailwind/WhatsNewButton.tsx

@@ -0,0 +1,56 @@
+'use client';
+
+// After copying, change these imports to '@thelol3882/sapar/...'
+import { useState } from 'react';
+import { useWhatsNew } from '../../src/react';
+import { WhatsNewPanel, type WhatsNewPanelProps } from './WhatsNewPanel';
+
+// Replace these with your design tokens.
+const styles = {
+    button: 'relative rounded-full p-2 text-neutral-600 hover:bg-neutral-100 focus-visible:outline-2 focus-visible:outline-indigo-500 dark:text-neutral-300 dark:hover:bg-neutral-800',
+    icon: 'size-5',
+    badge: 'absolute -right-0.5 -top-0.5 flex min-w-4 items-center justify-center rounded-full bg-red-500 px-1 text-[10px] font-semibold leading-4 text-white',
+};
+
+export interface WhatsNewButtonProps extends Pick<WhatsNewPanelProps, 'labels' | 'locale' | 'formatDate'> {
+    className?: string;
+    /** Accessible name; the unread count is appended. */
+    label?: string;
+}
+
+function SparkleIcon() {
+    return (
+        <svg
+            viewBox="0 0 24 24"
+            fill="none"
+            stroke="currentColor"
+            strokeWidth="2"
+            strokeLinecap="round"
+            strokeLinejoin="round"
+            className={styles.icon}
+            aria-hidden="true"
+        >
+            <path d="M9.9 15.5a2 2 0 0 0-1.4-1.4l-6.1-1.6a.5.5 0 0 1 0-1l6.1-1.6a2 2 0 0 0 1.4-1.4l1.6-6.1a.5.5 0 0 1 1 0l1.6 6.1a2 2 0 0 0 1.4 1.4l6.1 1.6a.5.5 0 0 1 0 1l-6.1 1.6a2 2 0 0 0-1.4 1.4l-1.6 6.1a.5.5 0 0 1-1 0zM20 3v4M22 5h-4M4 17v2M5 18H3" />
+        </svg>
+    );
+}
+
+export function WhatsNewButton({ className, label = "What's new", labels, locale, formatDate }: WhatsNewButtonProps) {
+    const [open, setOpen] = useState(false);
+    const { unreadCount } = useWhatsNew();
+
+    return (
+        <>
+            <button
+                type="button"
+                aria-label={unreadCount > 0 ? `${label} (${unreadCount})` : label}
+                onClick={() => setOpen(true)}
+                className={className ?? styles.button}
+            >
+                <SparkleIcon />
+                {unreadCount > 0 && <span className={styles.badge}>{unreadCount}</span>}
+            </button>
+            <WhatsNewPanel open={open} onClose={() => setOpen(false)} labels={labels} locale={locale} formatDate={formatDate} />
+        </>
+    );
+}