sefaria-ui-components 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,238 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { CSSProperties, ComponentType, ReactNode } from 'react';
+
+/**
+ * Simple event system for component-to-parent communication.
+ *
+ * Components emit events with a type and optional data payload.
+ * Parents handle events via a single onEvent callback.
+ *
+ * @example
+ * // In a component:
+ * type MyEvents = TextBlockEvent<'click', { x: number }> | TextBlockEvent<'hover'>;
+ * props.onEvent?.({ type: 'click', data: { x: 100 } });
+ *
+ * // In a parent:
+ * <TextBlock
+ *   onEvent={(event) => {
+ *     if (event.type === 'click') console.log(event.data.x);
+ *   }}
+ * />
+ */
+/**
+ * Base event type. All component events extend this.
+ */
+interface ComponentEvent<TType extends string = string, TData = undefined> {
+    type: TType;
+    data: TData;
+}
+/**
+ * Helper to create typed events for a component.
+ * The component name prefix helps with debugging and filtering.
+ *
+ * @example
+ * type ClickEvent = ComponentEventOf<'TextBlock', 'click', { x: number }>;
+ * // Results in: { type: 'TextBlock:click', data: { x: number } }
+ */
+type ComponentEventOf<TComponent extends string, TType extends string, TData = undefined> = ComponentEvent<`${TComponent}:${TType}`, TData>;
+/**
+ * Event handler type. Components accept this as their onEvent prop.
+ */
+type EventHandler<TEvent extends ComponentEvent<string, unknown> = ComponentEvent<string, unknown>> = (event: TEvent) => void;
+/**
+ * Helper to create an event object with proper typing.
+ */
+declare function createEvent<TType extends string, TData = undefined>(type: TType, data?: TData): ComponentEvent<TType, TData>;
+/**
+ * Helper to emit an event through an optional handler.
+ * Safely handles undefined handlers.
+ */
+declare function emitEvent<TEvent extends ComponentEvent>(handler: EventHandler<TEvent> | undefined, event: TEvent): void;
+/**
+ * Type guard to check if an event matches a specific type.
+ *
+ * @example
+ * if (isEventType(event, 'TextBlock:click')) {
+ *   // event.data is typed correctly
+ * }
+ */
+declare function isEventType<TEvent extends ComponentEvent, TType extends TEvent["type"]>(event: TEvent, type: TType): event is Extract<TEvent, {
+    type: TType;
+}>;
+
+type FollowupAction = "explain" | "summarize" | "translate" | "suggest_questions" | "commentary_top" | "commentary_consensus" | "commentary_disagreements" | "commentary_unusual" | "connect_to_life" | "trace_usage";
+declare const FOLLOWUP_MESSAGE_PREFIX = "__FOLLOWUP__";
+declare const FOLLOWUP_TEMPLATES: Record<FollowupAction, string>;
+declare function renderFollowupTemplate(action: FollowupAction, citation: string): string;
+declare function buildFollowupUserMessage(params: {
+    action: FollowupAction;
+    citation: string;
+    includeRePrefix: boolean;
+}): string;
+
+/**
+ * Response type from the Sefaria Text API.
+ */
+interface SefariaTextResponse {
+    ref?: string;
+    heRef?: string;
+    text?: unknown;
+    he?: unknown;
+    versions?: Array<{
+        text?: unknown;
+        language?: string;
+        versionTitle?: string;
+        isPrimary?: boolean;
+    }>;
+    sections?: unknown;
+    toSections?: unknown;
+    primary_category?: unknown;
+    type?: unknown;
+    categories?: unknown;
+    [key: string]: unknown;
+}
+/**
+ * Events emitted by TextBlock.
+ */
+type TextBlockClickEvent = ComponentEventOf<'TextBlock', 'click', {
+    ref: string;
+}>;
+type TextBlockLinkClickEvent = ComponentEventOf<'TextBlock', 'linkClick', {
+    ref: string;
+    href: string;
+}>;
+type TextBlockFollowupEvent = ComponentEventOf<'TextBlock', 'followup', {
+    ref: string;
+    action: FollowupAction;
+}>;
+type TextBlockEvent = TextBlockClickEvent | TextBlockLinkClickEvent | TextBlockFollowupEvent;
+interface TextBlockProps {
+    /** Sefaria citation reference (e.g., "Genesis 1:1") */
+    sefRef?: string;
+    /** Data from Sefaria Text API. If <code>sefariaData</code> is provided, renders full text. */
+    sefariaData?: SefariaTextResponse;
+    /** If true, fetches data from the Sefaria API when <code>sefariaData</code> is not provided. */
+    fetchData?: boolean;
+    /** Initial display <code>language</code>: translation, bilingual, or Hebrew. */
+    language?: string;
+    /** Preferred translation <code>versionTitle</code> from the Sefaria API. */
+    versionTitle?: string;
+    /** Show the "Follow up" button with action menu */
+    showFollowup?: boolean;
+    /** Event handler for component events */
+    onEvent?: EventHandler<TextBlockEvent>;
+    /** Additional CSS class name */
+    className?: string;
+    /** Additional inline styles */
+    style?: CSSProperties;
+}
+declare function TextBlockInner({ sefRef, sefariaData, fetchData, language, versionTitle, showFollowup, onEvent, className, style, }: TextBlockProps): react_jsx_runtime.JSX.Element;
+/**
+ * TextBlock displays a Sefaria text source with a colored border indicating its category.
+ *
+ * @example
+ * // Loading state - only <code>ref</code> provided
+ * <TextBlock ref="Genesis 1:1" />
+ *
+ * @example
+ * // Full render with data
+ * <TextBlock ref="Genesis 1:1" sefariaData={apiResponse} />
+ *
+ * @example
+ * // With event handling
+ * <TextBlock
+ *   ref="Genesis 1:1"
+ *   sefariaData={data}
+ *   onEvent={(event) => {
+ *     if (event.type === 'TextBlock:click') {
+ *       console.log('Clicked:', event.data.ref);
+ *     }
+ *   }}
+ * />
+ */
+declare const TextBlock: typeof TextBlockInner;
+
+interface GalleryExample<P = Record<string, unknown>> {
+    title: string;
+    description?: string;
+    props: P;
+    wrapper?: ComponentType<{
+        children: ReactNode;
+    }>;
+}
+interface GalleryConfig<P = Record<string, unknown>> {
+    name: string;
+    description: string;
+    /** Short noun phrase for overview cards (e.g., "Sefaria text display") */
+    shortDescription?: string;
+    component: ComponentType<P>;
+    examples: GalleryExample<P>[];
+    sourceCode: string;
+    /** Ordered list of props to display on docs pages. */
+    propsList?: string[];
+    /** Props for a simple example shown on the overview page */
+    overviewExample?: P;
+}
+
+declare const textBlockGallery: GalleryConfig<TextBlockProps>;
+
+interface CalendarBlockProps {
+    /** Calendar title in English, as returned by the API. */
+    calendar: string;
+    /** Show a text preview when no description is available. */
+    showText?: boolean;
+    /** Additional CSS class name */
+    className?: string;
+    /** Additional inline styles */
+    style?: CSSProperties;
+}
+declare function CalendarBlock({ calendar, showText, className, style }: CalendarBlockProps): react_jsx_runtime.JSX.Element;
+
+declare const colors: {
+    readonly darkteal: "#004e5f";
+    readonly raspberry: "#7c406f";
+    readonly green: "#5d956f";
+    readonly paleblue: "#9ab8cb";
+    readonly blue: "#4871bf";
+    readonly orange: "#cb6158";
+    readonly lightpink: "#c7a7b4";
+    readonly darkblue: "#073570";
+    readonly darkpink: "#ab4e66";
+    readonly lavender: "#7f85a9";
+    readonly yellow: "#ccb479";
+    readonly purple: "#594176";
+    readonly lightblue: "#5a99b7";
+    readonly lightgreen: "#97b386";
+    readonly red: "#802f3e";
+    readonly teal: "#00827f";
+    readonly lightbg: "#B8D4D3";
+    readonly tan: "#D4896C";
+};
+declare const categoryColors: Record<string, string>;
+declare function categoryColor(cat: unknown): string;
+declare const palette: {
+    colors: {
+        readonly darkteal: "#004e5f";
+        readonly raspberry: "#7c406f";
+        readonly green: "#5d956f";
+        readonly paleblue: "#9ab8cb";
+        readonly blue: "#4871bf";
+        readonly orange: "#cb6158";
+        readonly lightpink: "#c7a7b4";
+        readonly darkblue: "#073570";
+        readonly darkpink: "#ab4e66";
+        readonly lavender: "#7f85a9";
+        readonly yellow: "#ccb479";
+        readonly purple: "#594176";
+        readonly lightblue: "#5a99b7";
+        readonly lightgreen: "#97b386";
+        readonly red: "#802f3e";
+        readonly teal: "#00827f";
+        readonly lightbg: "#B8D4D3";
+        readonly tan: "#D4896C";
+    };
+    categoryColors: Record<string, string>;
+    categoryColor: typeof categoryColor;
+};
+
+export { CalendarBlock, type CalendarBlockProps, type ComponentEvent, type ComponentEventOf, type EventHandler, FOLLOWUP_MESSAGE_PREFIX, FOLLOWUP_TEMPLATES, type FollowupAction, type GalleryConfig, type GalleryExample, type SefariaTextResponse, TextBlock, type TextBlockClickEvent, type TextBlockEvent, type TextBlockLinkClickEvent, type TextBlockProps, buildFollowupUserMessage, categoryColor, categoryColors, colors, createEvent, emitEvent, isEventType, palette, renderFollowupTemplate, textBlockGallery };

package/dist/index.d.ts

@@ -0,0 +1,238 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { CSSProperties, ComponentType, ReactNode } from 'react';
+
+/**
+ * Simple event system for component-to-parent communication.
+ *
+ * Components emit events with a type and optional data payload.
+ * Parents handle events via a single onEvent callback.
+ *
+ * @example
+ * // In a component:
+ * type MyEvents = TextBlockEvent<'click', { x: number }> | TextBlockEvent<'hover'>;
+ * props.onEvent?.({ type: 'click', data: { x: 100 } });
+ *
+ * // In a parent:
+ * <TextBlock
+ *   onEvent={(event) => {
+ *     if (event.type === 'click') console.log(event.data.x);
+ *   }}
+ * />
+ */
+/**
+ * Base event type. All component events extend this.
+ */
+interface ComponentEvent<TType extends string = string, TData = undefined> {
+    type: TType;
+    data: TData;
+}
+/**
+ * Helper to create typed events for a component.
+ * The component name prefix helps with debugging and filtering.
+ *
+ * @example
+ * type ClickEvent = ComponentEventOf<'TextBlock', 'click', { x: number }>;
+ * // Results in: { type: 'TextBlock:click', data: { x: number } }
+ */
+type ComponentEventOf<TComponent extends string, TType extends string, TData = undefined> = ComponentEvent<`${TComponent}:${TType}`, TData>;
+/**
+ * Event handler type. Components accept this as their onEvent prop.
+ */
+type EventHandler<TEvent extends ComponentEvent<string, unknown> = ComponentEvent<string, unknown>> = (event: TEvent) => void;
+/**
+ * Helper to create an event object with proper typing.
+ */
+declare function createEvent<TType extends string, TData = undefined>(type: TType, data?: TData): ComponentEvent<TType, TData>;
+/**
+ * Helper to emit an event through an optional handler.
+ * Safely handles undefined handlers.
+ */
+declare function emitEvent<TEvent extends ComponentEvent>(handler: EventHandler<TEvent> | undefined, event: TEvent): void;
+/**
+ * Type guard to check if an event matches a specific type.
+ *
+ * @example
+ * if (isEventType(event, 'TextBlock:click')) {
+ *   // event.data is typed correctly
+ * }
+ */
+declare function isEventType<TEvent extends ComponentEvent, TType extends TEvent["type"]>(event: TEvent, type: TType): event is Extract<TEvent, {
+    type: TType;
+}>;
+
+type FollowupAction = "explain" | "summarize" | "translate" | "suggest_questions" | "commentary_top" | "commentary_consensus" | "commentary_disagreements" | "commentary_unusual" | "connect_to_life" | "trace_usage";
+declare const FOLLOWUP_MESSAGE_PREFIX = "__FOLLOWUP__";
+declare const FOLLOWUP_TEMPLATES: Record<FollowupAction, string>;
+declare function renderFollowupTemplate(action: FollowupAction, citation: string): string;
+declare function buildFollowupUserMessage(params: {
+    action: FollowupAction;
+    citation: string;
+    includeRePrefix: boolean;
+}): string;
+
+/**
+ * Response type from the Sefaria Text API.
+ */
+interface SefariaTextResponse {
+    ref?: string;
+    heRef?: string;
+    text?: unknown;
+    he?: unknown;
+    versions?: Array<{
+        text?: unknown;
+        language?: string;
+        versionTitle?: string;
+        isPrimary?: boolean;
+    }>;
+    sections?: unknown;
+    toSections?: unknown;
+    primary_category?: unknown;
+    type?: unknown;
+    categories?: unknown;
+    [key: string]: unknown;
+}
+/**
+ * Events emitted by TextBlock.
+ */
+type TextBlockClickEvent = ComponentEventOf<'TextBlock', 'click', {
+    ref: string;
+}>;
+type TextBlockLinkClickEvent = ComponentEventOf<'TextBlock', 'linkClick', {
+    ref: string;
+    href: string;
+}>;
+type TextBlockFollowupEvent = ComponentEventOf<'TextBlock', 'followup', {
+    ref: string;
+    action: FollowupAction;
+}>;
+type TextBlockEvent = TextBlockClickEvent | TextBlockLinkClickEvent | TextBlockFollowupEvent;
+interface TextBlockProps {
+    /** Sefaria citation reference (e.g., "Genesis 1:1") */
+    sefRef?: string;
+    /** Data from Sefaria Text API. If <code>sefariaData</code> is provided, renders full text. */
+    sefariaData?: SefariaTextResponse;
+    /** If true, fetches data from the Sefaria API when <code>sefariaData</code> is not provided. */
+    fetchData?: boolean;
+    /** Initial display <code>language</code>: translation, bilingual, or Hebrew. */
+    language?: string;
+    /** Preferred translation <code>versionTitle</code> from the Sefaria API. */
+    versionTitle?: string;
+    /** Show the "Follow up" button with action menu */
+    showFollowup?: boolean;
+    /** Event handler for component events */
+    onEvent?: EventHandler<TextBlockEvent>;
+    /** Additional CSS class name */
+    className?: string;
+    /** Additional inline styles */
+    style?: CSSProperties;
+}
+declare function TextBlockInner({ sefRef, sefariaData, fetchData, language, versionTitle, showFollowup, onEvent, className, style, }: TextBlockProps): react_jsx_runtime.JSX.Element;
+/**
+ * TextBlock displays a Sefaria text source with a colored border indicating its category.
+ *
+ * @example
+ * // Loading state - only <code>ref</code> provided
+ * <TextBlock ref="Genesis 1:1" />
+ *
+ * @example
+ * // Full render with data
+ * <TextBlock ref="Genesis 1:1" sefariaData={apiResponse} />
+ *
+ * @example
+ * // With event handling
+ * <TextBlock
+ *   ref="Genesis 1:1"
+ *   sefariaData={data}
+ *   onEvent={(event) => {
+ *     if (event.type === 'TextBlock:click') {
+ *       console.log('Clicked:', event.data.ref);
+ *     }
+ *   }}
+ * />
+ */
+declare const TextBlock: typeof TextBlockInner;
+
+interface GalleryExample<P = Record<string, unknown>> {
+    title: string;
+    description?: string;
+    props: P;
+    wrapper?: ComponentType<{
+        children: ReactNode;
+    }>;
+}
+interface GalleryConfig<P = Record<string, unknown>> {
+    name: string;
+    description: string;
+    /** Short noun phrase for overview cards (e.g., "Sefaria text display") */
+    shortDescription?: string;
+    component: ComponentType<P>;
+    examples: GalleryExample<P>[];
+    sourceCode: string;
+    /** Ordered list of props to display on docs pages. */
+    propsList?: string[];
+    /** Props for a simple example shown on the overview page */
+    overviewExample?: P;
+}
+
+declare const textBlockGallery: GalleryConfig<TextBlockProps>;
+
+interface CalendarBlockProps {
+    /** Calendar title in English, as returned by the API. */
+    calendar: string;
+    /** Show a text preview when no description is available. */
+    showText?: boolean;
+    /** Additional CSS class name */
+    className?: string;
+    /** Additional inline styles */
+    style?: CSSProperties;
+}
+declare function CalendarBlock({ calendar, showText, className, style }: CalendarBlockProps): react_jsx_runtime.JSX.Element;
+
+declare const colors: {
+    readonly darkteal: "#004e5f";
+    readonly raspberry: "#7c406f";
+    readonly green: "#5d956f";
+    readonly paleblue: "#9ab8cb";
+    readonly blue: "#4871bf";
+    readonly orange: "#cb6158";
+    readonly lightpink: "#c7a7b4";
+    readonly darkblue: "#073570";
+    readonly darkpink: "#ab4e66";
+    readonly lavender: "#7f85a9";
+    readonly yellow: "#ccb479";
+    readonly purple: "#594176";
+    readonly lightblue: "#5a99b7";
+    readonly lightgreen: "#97b386";
+    readonly red: "#802f3e";
+    readonly teal: "#00827f";
+    readonly lightbg: "#B8D4D3";
+    readonly tan: "#D4896C";
+};
+declare const categoryColors: Record<string, string>;
+declare function categoryColor(cat: unknown): string;
+declare const palette: {
+    colors: {
+        readonly darkteal: "#004e5f";
+        readonly raspberry: "#7c406f";
+        readonly green: "#5d956f";
+        readonly paleblue: "#9ab8cb";
+        readonly blue: "#4871bf";
+        readonly orange: "#cb6158";
+        readonly lightpink: "#c7a7b4";
+        readonly darkblue: "#073570";
+        readonly darkpink: "#ab4e66";
+        readonly lavender: "#7f85a9";
+        readonly yellow: "#ccb479";
+        readonly purple: "#594176";
+        readonly lightblue: "#5a99b7";
+        readonly lightgreen: "#97b386";
+        readonly red: "#802f3e";
+        readonly teal: "#00827f";
+        readonly lightbg: "#B8D4D3";
+        readonly tan: "#D4896C";
+    };
+    categoryColors: Record<string, string>;
+    categoryColor: typeof categoryColor;
+};
+
+export { CalendarBlock, type CalendarBlockProps, type ComponentEvent, type ComponentEventOf, type EventHandler, FOLLOWUP_MESSAGE_PREFIX, FOLLOWUP_TEMPLATES, type FollowupAction, type GalleryConfig, type GalleryExample, type SefariaTextResponse, TextBlock, type TextBlockClickEvent, type TextBlockEvent, type TextBlockLinkClickEvent, type TextBlockProps, buildFollowupUserMessage, categoryColor, categoryColors, colors, createEvent, emitEvent, isEventType, palette, renderFollowupTemplate, textBlockGallery };