@zoiq.io/dev-kit 0.1.0

package/README.md

@@ -0,0 +1,96 @@
+# ZOIQ
+
+React component library and framework with **project-key-driven theme**, hooks, and UI primitives. Use a single project key to auto-configure colors, fonts, and branding across your app.
+
+## Install
+
+```bash
+npm install zoiq
+```
+
+Peer dependencies: `react`, `react-dom` (>=18).
+
+## Quick start
+
+Wrap your app with `ZOIQProvider` and pass your project key (and optional API base URL):
+
+```tsx
+import { ZOIQProvider, Page, Header, Text, useProjectSettings } from 'zoiq'
+
+function App() {
+  return (
+    <ZOIQProvider projectKey="your-project-id" apiBaseUrl="https://your-portal.com">
+      <Page>
+        <Header left={<Logo />} right={<UserMenu />} />
+        <Text>Content with theme applied</Text>
+      </Page>
+    </ZOIQProvider>
+  )
+}
+```
+
+## ZOIQProvider
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `projectKey` | `string` | **Required.** Project ID or public front-end key used to fetch theme and config. |
+| `apiBaseUrl` | `string` | Optional. Base URL for the project config API. Defaults to `window.location.origin` (same origin). |
+| `fetchProjectConfig` | `(key: string) => Promise<ProjectSettings \| null>` | Optional. Custom fetcher; if provided, `apiBaseUrl` is ignored for config. |
+
+The provider:
+
+1. Fetches project theme (styleGuide, branding, definedColors, navbarSettings) from `GET {apiBaseUrl}/api/zoiq/project/{projectKey}`.
+2. Applies theme by setting CSS variables on `document.documentElement` and optional font links.
+3. Exposes the same config via context for `useProjectSettings` and other hooks.
+
+## Hooks
+
+### useProjectSettings()
+
+Returns the full project theme/settings (same data the provider used to apply theme). Use within `ZOIQProvider`.
+
+```tsx
+const { data, loading, error, refetch } = useProjectSettings()
+// data: ProjectSettings | null (styleGuide, branding, definedColors, navbarSettings)
+```
+
+### useSectionFlags()
+
+Returns which section IDs are enabled or disabled for the current project (e.g. for feature gating or nav). Uses `GET {apiBaseUrl}/api/zoiq/project/{projectKey}/sections`.
+
+```tsx
+const { enabledIds, disabledIds, loading, error, refetch } = useSectionFlags()
+// enabledIds: Set<string>, disabledIds: Set<string>
+```
+
+### useZOIQApi\<T\>(entity, options?)
+
+Fetches custom entity data for the current project. Uses `GET {apiBaseUrl}/api/zoiq/project/{projectKey}/data/{entity}?id=...`.
+
+```tsx
+const { data, loading, error, refetch } = useZOIQApi<PageType>('pages', { id: 'abc' })
+```
+
+Supported entities (when using the default portal API): `pages`, `siteData`.
+
+## Components
+
+- **Atoms:** `Text`, `Title`, `Subtitle`, `ScrollButton`, `ToggleTheme`
+- **Molecules:** `Section`, `ToastContainer` (placeholder; use your own toast library)
+- **Layout:** `Page`, `Header`, `Footer`, `SecondarySidebar`
+
+All components use CSS variables (e.g. `var(--primary)`, `var(--text-primary)`) so ZOIQProvider’s theme applies automatically.
+
+## API (backend)
+
+The default client expects these endpoints on the host (e.g. your portal):
+
+- `GET /api/zoiq/project/[projectKey]` → project theme (styleGuide, branding, definedColors, navbarSettings)
+- `GET /api/zoiq/project/[projectKey]/sections` → `{ enabledIds: string[], disabledIds: string[] }`
+- `GET /api/zoiq/project/[projectKey]/data/[entity]?id=...` → entity data (e.g. `pages`, `siteData`)
+
+You can bypass these by passing a custom `fetchProjectConfig` to `ZOIQProvider`.
+
+## License
+
+See repository license.

package/dist/index.d.mts

@@ -0,0 +1,236 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React from 'react';
+
+/**
+ * Project theme/settings shape returned by the config API and consumed by ZOIQProvider.
+ */
+interface ProjectSettings {
+    styleGuide?: Record<string, string | null> | null;
+    branding?: {
+        navbarLogo?: {
+            fileID?: string | null;
+            link?: string | null;
+        } | null;
+        footerLogo?: {
+            fileID?: string | null;
+            link?: string | null;
+        } | null;
+        loaderLogo?: {
+            fileID?: string | null;
+            link?: string | null;
+        } | null;
+        faviconLogo?: {
+            fileID?: string | null;
+            link?: string | null;
+        } | null;
+        authImage?: {
+            fileID?: string | null;
+            link?: string | null;
+        } | null;
+        customLogos?: Array<{
+            name: string;
+            description?: string | null;
+            fileID?: string | null;
+            link?: string | null;
+        } | null> | null;
+        primaryFont?: {
+            name?: string | null;
+            link?: string | null;
+        } | null;
+        secondaryFont?: {
+            name?: string | null;
+            link?: string | null;
+        } | null;
+        tertiaryFont?: {
+            name?: string | null;
+            link?: string | null;
+        } | null;
+    } | null;
+    definedColors?: Array<{
+        id: string;
+        name: string;
+        value: string;
+    } | null> | null;
+    clientDefinedColors?: Array<{
+        name: string;
+        description?: string | null;
+        definedColor?: {
+            name: string;
+            value: string;
+        } | null;
+    } | null> | null;
+    navbarSettings?: {
+        isSticky?: boolean | null;
+        fontSize?: string | null;
+        alignment?: string | null;
+        logoSize?: string | null;
+        navbarType?: string | null;
+        gutters?: string | null;
+        subCategoryAnimation?: string | null;
+    } | null;
+}
+/**
+ * Section flag: enabled/disabled per section ID.
+ */
+interface SectionFlag {
+    id: string;
+    enabled: boolean;
+}
+/**
+ * Response shape for section flags API.
+ */
+interface SectionFlagsData {
+    enabledIds: string[];
+    disabledIds: string[];
+}
+
+interface ZOIQProviderProps {
+    /** Project key (e.g. project ID or public API key) to fetch theme and config */
+    projectKey: string;
+    /** Base URL for the project config API (e.g. https://your-portal.com/api/zoiq) */
+    apiBaseUrl?: string;
+    /** Optional custom fetcher; if provided, apiBaseUrl is ignored for config fetch */
+    fetchProjectConfig?: (key: string) => Promise<ProjectSettings | null>;
+    children: React.ReactNode;
+}
+interface ZOIQContextValue {
+    projectKey: string;
+    apiBaseUrl?: string;
+    settings: ProjectSettings | null;
+    loading: boolean;
+    error: Error | null;
+    refetch: () => Promise<void>;
+}
+declare function ZOIQProvider({ projectKey, apiBaseUrl, fetchProjectConfig: customFetch, children, }: ZOIQProviderProps): react_jsx_runtime.JSX.Element;
+declare function useZOIQContext(): ZOIQContextValue | null;
+
+interface UseProjectSettingsResult {
+    data: ProjectSettings | null;
+    loading: boolean;
+    error: Error | null;
+    refetch: () => Promise<void>;
+}
+/**
+ * Returns the full project theme/settings for the current project key.
+ * Must be used within ZOIQProvider. Data is the same that the provider used to apply theme.
+ */
+declare function useProjectSettings(): UseProjectSettingsResult;
+
+interface UseSectionFlagsResult {
+    enabledIds: Set<string>;
+    disabledIds: Set<string>;
+    loading: boolean;
+    error: Error | null;
+    refetch: () => Promise<void>;
+}
+/**
+ * Returns which section IDs are enabled or disabled for the current project.
+ * Must be used within ZOIQProvider. Uses the same apiBaseUrl as the provider.
+ */
+declare function useSectionFlags(): UseSectionFlagsResult;
+
+interface UseZOIQApiOptions {
+    id?: string;
+    query?: Record<string, string>;
+}
+interface UseZOIQApiResult<T> {
+    data: T | null;
+    loading: boolean;
+    error: Error | null;
+    refetch: () => Promise<void>;
+}
+/**
+ * Fetches custom entity data for the current project.
+ * Must be used within ZOIQProvider.
+ */
+declare function useZOIQApi<T = unknown>(entity: string, options?: UseZOIQApiOptions): UseZOIQApiResult<T>;
+
+interface TextProps extends React.HTMLAttributes<HTMLElement> {
+    children?: React.ReactNode;
+    className?: string;
+    as?: 'span' | 'p' | 'div';
+}
+declare const Text: ({ children, className, as: As, ...props }: TextProps) => react_jsx_runtime.JSX.Element;
+
+interface TitleProps {
+    children?: React.ReactNode;
+    className?: string;
+}
+declare const Title: ({ children, className }: TitleProps) => react_jsx_runtime.JSX.Element;
+
+interface SubtitleProps {
+    children?: React.ReactNode;
+    className?: string;
+}
+declare const Subtitle: ({ children, className }: SubtitleProps) => react_jsx_runtime.JSX.Element;
+
+interface ScrollButtonProps {
+    className?: string;
+    /** Scroll Y threshold above which the button is shown (default 200) */
+    threshold?: number;
+}
+declare const ScrollButton: ({ className, threshold }: ScrollButtonProps) => react_jsx_runtime.JSX.Element;
+
+interface ToggleThemeProps {
+    className?: string;
+    /** Callback when user requests theme toggle; host app controls actual theme state */
+    onToggle?: () => void;
+    /** Optional current theme name for rendering (e.g. "light" | "dark") */
+    theme?: string;
+    /** Content to show (e.g. icon). If not provided, shows "Theme" */
+    children?: React.ReactNode;
+}
+declare const ToggleTheme: ({ className, onToggle, theme, children }: ToggleThemeProps) => react_jsx_runtime.JSX.Element;
+
+interface SectionProps {
+    children?: React.ReactNode;
+    className?: string;
+}
+declare const Section: ({ children, className }: SectionProps) => react_jsx_runtime.JSX.Element;
+
+/**
+ * Placeholder for toast container. Host app should render Toaster from "sonner" (or similar)
+ * inside the app; ZOIQ does not bundle a toast library.
+ */
+declare const ToastContainer: () => null;
+
+interface PageProps {
+    children?: React.ReactNode;
+    className?: string;
+    /** Optional full-width layout (no horizontal padding) */
+    fullWidth?: boolean;
+}
+declare const Page: ({ children, className, fullWidth }: PageProps) => react_jsx_runtime.JSX.Element;
+
+interface HeaderProps {
+    children?: React.ReactNode;
+    className?: string;
+    /** Optional left slot (e.g. logo, nav) */
+    left?: React.ReactNode;
+    /** Optional right slot (e.g. user menu, theme toggle) */
+    right?: React.ReactNode;
+}
+declare const Header: ({ children, className, left, right }: HeaderProps) => react_jsx_runtime.JSX.Element;
+
+interface FooterProps {
+    children?: React.ReactNode;
+    className?: string;
+}
+declare const Footer: ({ children, className }: FooterProps) => react_jsx_runtime.JSX.Element;
+
+interface SecondarySidebarItem {
+    label: string;
+    href: string;
+    icon?: React.ReactNode;
+}
+interface SecondarySidebarProps {
+    items: SecondarySidebarItem[];
+    className?: string;
+    /** Optional: return true if item is active (e.g. from pathname) */
+    isActive?: (item: SecondarySidebarItem) => boolean;
+    /** Optional: custom link renderer (e.g. Next.js Link). Default: <a> */
+    renderLink?: (item: SecondarySidebarItem, children: React.ReactNode) => React.ReactNode;
+}
+declare const SecondarySidebar: ({ items, className, isActive, renderLink }: SecondarySidebarProps) => react_jsx_runtime.JSX.Element;
+
+export { Footer, Header, Page, type ProjectSettings, ScrollButton, SecondarySidebar, type SecondarySidebarItem, type SecondarySidebarProps, Section, type SectionFlag, type SectionFlagsData, Subtitle, Text, Title, ToastContainer, ToggleTheme, ZOIQProvider, useProjectSettings, useSectionFlags, useZOIQApi, useZOIQContext };

package/dist/index.d.ts

@@ -0,0 +1,236 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React from 'react';
+
+/**
+ * Project theme/settings shape returned by the config API and consumed by ZOIQProvider.
+ */
+interface ProjectSettings {
+    styleGuide?: Record<string, string | null> | null;
+    branding?: {
+        navbarLogo?: {
+            fileID?: string | null;
+            link?: string | null;
+        } | null;
+        footerLogo?: {
+            fileID?: string | null;
+            link?: string | null;
+        } | null;
+        loaderLogo?: {
+            fileID?: string | null;
+            link?: string | null;
+        } | null;
+        faviconLogo?: {
+            fileID?: string | null;
+            link?: string | null;
+        } | null;
+        authImage?: {
+            fileID?: string | null;
+            link?: string | null;
+        } | null;
+        customLogos?: Array<{
+            name: string;
+            description?: string | null;
+            fileID?: string | null;
+            link?: string | null;
+        } | null> | null;
+        primaryFont?: {
+            name?: string | null;
+            link?: string | null;
+        } | null;
+        secondaryFont?: {
+            name?: string | null;
+            link?: string | null;
+        } | null;
+        tertiaryFont?: {
+            name?: string | null;
+            link?: string | null;
+        } | null;
+    } | null;
+    definedColors?: Array<{
+        id: string;
+        name: string;
+        value: string;
+    } | null> | null;
+    clientDefinedColors?: Array<{
+        name: string;
+        description?: string | null;
+        definedColor?: {
+            name: string;
+            value: string;
+        } | null;
+    } | null> | null;
+    navbarSettings?: {
+        isSticky?: boolean | null;
+        fontSize?: string | null;
+        alignment?: string | null;
+        logoSize?: string | null;
+        navbarType?: string | null;
+        gutters?: string | null;
+        subCategoryAnimation?: string | null;
+    } | null;
+}
+/**
+ * Section flag: enabled/disabled per section ID.
+ */
+interface SectionFlag {
+    id: string;
+    enabled: boolean;
+}
+/**
+ * Response shape for section flags API.
+ */
+interface SectionFlagsData {
+    enabledIds: string[];
+    disabledIds: string[];
+}
+
+interface ZOIQProviderProps {
+    /** Project key (e.g. project ID or public API key) to fetch theme and config */
+    projectKey: string;
+    /** Base URL for the project config API (e.g. https://your-portal.com/api/zoiq) */
+    apiBaseUrl?: string;
+    /** Optional custom fetcher; if provided, apiBaseUrl is ignored for config fetch */
+    fetchProjectConfig?: (key: string) => Promise<ProjectSettings | null>;
+    children: React.ReactNode;
+}
+interface ZOIQContextValue {
+    projectKey: string;
+    apiBaseUrl?: string;
+    settings: ProjectSettings | null;
+    loading: boolean;
+    error: Error | null;
+    refetch: () => Promise<void>;
+}
+declare function ZOIQProvider({ projectKey, apiBaseUrl, fetchProjectConfig: customFetch, children, }: ZOIQProviderProps): react_jsx_runtime.JSX.Element;
+declare function useZOIQContext(): ZOIQContextValue | null;
+
+interface UseProjectSettingsResult {
+    data: ProjectSettings | null;
+    loading: boolean;
+    error: Error | null;
+    refetch: () => Promise<void>;
+}
+/**
+ * Returns the full project theme/settings for the current project key.
+ * Must be used within ZOIQProvider. Data is the same that the provider used to apply theme.
+ */
+declare function useProjectSettings(): UseProjectSettingsResult;
+
+interface UseSectionFlagsResult {
+    enabledIds: Set<string>;
+    disabledIds: Set<string>;
+    loading: boolean;
+    error: Error | null;
+    refetch: () => Promise<void>;
+}
+/**
+ * Returns which section IDs are enabled or disabled for the current project.
+ * Must be used within ZOIQProvider. Uses the same apiBaseUrl as the provider.
+ */
+declare function useSectionFlags(): UseSectionFlagsResult;
+
+interface UseZOIQApiOptions {
+    id?: string;
+    query?: Record<string, string>;
+}
+interface UseZOIQApiResult<T> {
+    data: T | null;
+    loading: boolean;
+    error: Error | null;
+    refetch: () => Promise<void>;
+}
+/**
+ * Fetches custom entity data for the current project.
+ * Must be used within ZOIQProvider.
+ */
+declare function useZOIQApi<T = unknown>(entity: string, options?: UseZOIQApiOptions): UseZOIQApiResult<T>;
+
+interface TextProps extends React.HTMLAttributes<HTMLElement> {
+    children?: React.ReactNode;
+    className?: string;
+    as?: 'span' | 'p' | 'div';
+}
+declare const Text: ({ children, className, as: As, ...props }: TextProps) => react_jsx_runtime.JSX.Element;
+
+interface TitleProps {
+    children?: React.ReactNode;
+    className?: string;
+}
+declare const Title: ({ children, className }: TitleProps) => react_jsx_runtime.JSX.Element;
+
+interface SubtitleProps {
+    children?: React.ReactNode;
+    className?: string;
+}
+declare const Subtitle: ({ children, className }: SubtitleProps) => react_jsx_runtime.JSX.Element;
+
+interface ScrollButtonProps {
+    className?: string;
+    /** Scroll Y threshold above which the button is shown (default 200) */
+    threshold?: number;
+}
+declare const ScrollButton: ({ className, threshold }: ScrollButtonProps) => react_jsx_runtime.JSX.Element;
+
+interface ToggleThemeProps {
+    className?: string;
+    /** Callback when user requests theme toggle; host app controls actual theme state */
+    onToggle?: () => void;
+    /** Optional current theme name for rendering (e.g. "light" | "dark") */
+    theme?: string;
+    /** Content to show (e.g. icon). If not provided, shows "Theme" */
+    children?: React.ReactNode;
+}
+declare const ToggleTheme: ({ className, onToggle, theme, children }: ToggleThemeProps) => react_jsx_runtime.JSX.Element;
+
+interface SectionProps {
+    children?: React.ReactNode;
+    className?: string;
+}
+declare const Section: ({ children, className }: SectionProps) => react_jsx_runtime.JSX.Element;
+
+/**
+ * Placeholder for toast container. Host app should render Toaster from "sonner" (or similar)
+ * inside the app; ZOIQ does not bundle a toast library.
+ */
+declare const ToastContainer: () => null;
+
+interface PageProps {
+    children?: React.ReactNode;
+    className?: string;
+    /** Optional full-width layout (no horizontal padding) */
+    fullWidth?: boolean;
+}
+declare const Page: ({ children, className, fullWidth }: PageProps) => react_jsx_runtime.JSX.Element;
+
+interface HeaderProps {
+    children?: React.ReactNode;
+    className?: string;
+    /** Optional left slot (e.g. logo, nav) */
+    left?: React.ReactNode;
+    /** Optional right slot (e.g. user menu, theme toggle) */
+    right?: React.ReactNode;
+}
+declare const Header: ({ children, className, left, right }: HeaderProps) => react_jsx_runtime.JSX.Element;
+
+interface FooterProps {
+    children?: React.ReactNode;
+    className?: string;
+}
+declare const Footer: ({ children, className }: FooterProps) => react_jsx_runtime.JSX.Element;
+
+interface SecondarySidebarItem {
+    label: string;
+    href: string;
+    icon?: React.ReactNode;
+}
+interface SecondarySidebarProps {
+    items: SecondarySidebarItem[];
+    className?: string;
+    /** Optional: return true if item is active (e.g. from pathname) */
+    isActive?: (item: SecondarySidebarItem) => boolean;
+    /** Optional: custom link renderer (e.g. Next.js Link). Default: <a> */
+    renderLink?: (item: SecondarySidebarItem, children: React.ReactNode) => React.ReactNode;
+}
+declare const SecondarySidebar: ({ items, className, isActive, renderLink }: SecondarySidebarProps) => react_jsx_runtime.JSX.Element;
+
+export { Footer, Header, Page, type ProjectSettings, ScrollButton, SecondarySidebar, type SecondarySidebarItem, type SecondarySidebarProps, Section, type SectionFlag, type SectionFlagsData, Subtitle, Text, Title, ToastContainer, ToggleTheme, ZOIQProvider, useProjectSettings, useSectionFlags, useZOIQApi, useZOIQContext };