rootzz-layout 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,462 @@
+import * as react from 'react';
+import { ElementType, ReactNode, MouseEvent, CSSProperties, InputHTMLAttributes, ButtonHTMLAttributes } from 'react';
+
+/** Tema visual do layout. */
+type ThemeMode = 'light' | 'dark';
+/**
+ * Componente usado para renderizar links de navegação (itens da sidebar, logo, etc.).
+ * Por padrão é uma tag `<a>`. Passe o `Link` do seu router (Next.js, React Router…)
+ * para navegação SPA sem recarregar a página. Recebe `href`, `className` e `children`.
+ */
+type LinkComponent = ElementType;
+/** Um aplicativo no menu de apps (formato de `applications.json` da Eduzz). */
+interface AppItem {
+    /** Identificador da aplicação (ex.: "orbita"). */
+    application?: string;
+    /** Nome exibido (ex.: "MyEduzz"). */
+    label: string;
+    /** URL do ícone (SVG/PNG). */
+    icon: string;
+    /** Descrição curta (usada como tooltip). */
+    description?: string;
+    /** Destino ao clicar. */
+    url: string;
+}
+/**
+ * Fonte dos apps do menu de grade:
+ * - `true` → busca a lista padrão da Eduzz no CDN.
+ * - `false`/omitido → não exibe o botão de apps.
+ * - `AppItem[]` → lista estática que você fornece.
+ * - `string` → URL custom de onde buscar o JSON.
+ * - `{ url }` / `{ items }` → forma objeto equivalente.
+ */
+type AppsSource = boolean | string | AppItem[] | {
+    url?: string;
+    items?: AppItem[];
+};
+/** Configuração do logo exibido na topbar. */
+interface LogoConfig {
+    /** URL da imagem do logo. */
+    src: string;
+    /** Texto alternativo (acessibilidade). */
+    alt?: string;
+    /** Se informado, o logo vira um link para esta URL. */
+    href?: string;
+    /** Callback ao clicar no logo. */
+    onClick?: () => void;
+    /** Altura do logo (px ou string CSS). Padrão: 28. */
+    height?: number | string;
+}
+/** Item de ação no dropdown do usuário. */
+interface UserMenuItem {
+    key?: string;
+    /** Rótulo da ação. */
+    label: ReactNode;
+    /** Ícone opcional à esquerda. */
+    icon?: ReactNode;
+    /** Ação ao clicar. */
+    onClick?: () => void;
+    /** Se informado, renderiza como link. */
+    href?: string;
+    /** Estilo de ação destrutiva (ex.: "Sair"). */
+    danger?: boolean;
+    /** Desabilita o item. */
+    disabled?: boolean;
+}
+/** Divisor no dropdown do usuário. */
+interface UserMenuDivider {
+    type: 'divider';
+    key?: string;
+}
+type UserMenuEntry = UserMenuItem | UserMenuDivider;
+/** Configuração do usuário exibido à direita da topbar. */
+interface UserConfig {
+    /** Nome exibido (truncado se longo). */
+    name: string;
+    /** E-mail/subtítulo opcional no cabeçalho do dropdown. */
+    email?: string;
+    /** URL do avatar. Se ausente, usa `initials`. */
+    avatarUrl?: string;
+    /** Iniciais exibidas quando não há avatar (ex.: "Dd"). Calculadas do nome se omitido. */
+    initials?: string;
+    /** Itens de ação do dropdown. Se vazio/omitido, o clique chama `onClick`. */
+    menu?: UserMenuEntry[];
+    /** Clique no usuário quando não há `menu`. */
+    onClick?: () => void;
+}
+/** Item simples (link) da sidebar. */
+interface MenuLink {
+    type?: 'item';
+    /** Chave única — usada para casar com `activeKey`. */
+    key: string;
+    /** Rótulo. */
+    label: ReactNode;
+    /** Ícone à esquerda. */
+    icon?: ReactNode;
+    /** Destino. Renderiza com `linkComponent` (padrão `<a>`). */
+    href?: string;
+    /** `target` do link (ex.: "_blank"). */
+    target?: string;
+    /** Clique (alternativa a `href`). */
+    onClick?: (event: MouseEvent) => void;
+    /** Marca o item como ativo manualmente (sobrepõe `activeKey`). */
+    active?: boolean;
+    /** Conteúdo à direita (ex.: contador, tag). */
+    badge?: ReactNode;
+    /** Desabilita o item. */
+    disabled?: boolean;
+}
+/** Grupo colapsável de itens na sidebar. */
+interface MenuGroup {
+    type: 'group';
+    /** Chave única do grupo. */
+    key: string;
+    /** Rótulo do grupo (geralmente em maiúsculas). */
+    label: ReactNode;
+    /** Ícone opcional do grupo. */
+    icon?: ReactNode;
+    /** Itens filhos. */
+    items: MenuLink[];
+    /** Inicia colapsado. Padrão: `false`. */
+    defaultCollapsed?: boolean;
+    /** Permite colapsar/expandir. Padrão: `true`. Se `false`, fica sempre aberto. */
+    collapsible?: boolean;
+}
+/** Divisor entre itens da sidebar. */
+interface MenuDivider {
+    type: 'divider';
+    key?: string;
+}
+/** Qualquer entrada da sidebar. */
+type MenuItem = MenuLink | MenuGroup | MenuDivider;
+/**
+ * Props do shell `<RootzzLayout>`. É um componente composto — passe
+ * `RootzzLayout.Topbar`, `RootzzLayout.Sidebar` e `RootzzLayout.Content` como
+ * filhos, cada um com suas próprias props. Aqui ficam apenas configs de
+ * nível de shell (tema e componente de link), compartilhadas por todos.
+ */
+interface RootzzLayoutProps {
+    /** Subcomponentes: `RootzzLayout.Topbar`, `.Sidebar`, `.Content`. */
+    children?: ReactNode;
+    /** Tema controlado. Se informado, você gerencia o estado via `onThemeChange`. */
+    theme?: ThemeMode;
+    /** Tema inicial quando não-controlado. Padrão: `'light'`. */
+    defaultTheme?: ThemeMode;
+    /** Chamado quando o tema muda (toggle ou API). */
+    onThemeChange?: (theme: ThemeMode) => void;
+    /**
+     * Componente para renderizar links de navegação (padrão `<a>`), usado por
+     * topbar e sidebar. Passe o `Link` do seu router para navegação SPA.
+     */
+    linkComponent?: LinkComponent;
+    /** Classe extra no elemento raiz (`.rootzz-layout`). */
+    className?: string;
+    /** Estilo inline no elemento raiz — útil para sobrescrever tokens `--rzl-*`. */
+    style?: CSSProperties;
+    /** `id` do elemento raiz. */
+    id?: string;
+}
+
+interface ContentProps {
+    children?: ReactNode;
+    /**
+     * Largura máxima do conteúdo. `false` ocupa 100%.
+     * Omitido usa o token `--rzl-content-max-width`.
+     */
+    maxWidth?: number | string | false;
+    /** Classe extra no wrapper interno. */
+    className?: string;
+    /** Remove o padding padrão. */
+    noPadding?: boolean;
+}
+/** Área de conteúdo: rola verticalmente e centraliza/limita a largura do que for inserido. */
+declare function Content({ children, maxWidth, className, noPadding }: ContentProps): react.JSX.Element;
+
+interface SidebarProps {
+    /** Entradas do menu (links, grupos, divisores). */
+    menu?: MenuItem[];
+    /** Chave do item ativo (casa com `MenuLink.key`). */
+    activeKey?: string;
+    /** Conteúdo fixo no topo. */
+    header?: ReactNode;
+    /** Conteúdo fixo no rodapé. */
+    footer?: ReactNode;
+    /** Rótulo acessível da navegação. Padrão: "Navegação principal". */
+    ariaLabel?: string;
+    /** Conteúdo custom (substitui `menu` se quiser compor manualmente). */
+    children?: ReactNode;
+    className?: string;
+    /** Título do drawer mobile. */
+    mobileTitle?: ReactNode;
+}
+/**
+ * Sidebar de navegação.
+ * - Desktop (≥768px): coluna fixa com largura `--rzl-sidebar-width`.
+ * - Mobile (<768px): drawer off-canvas com overlay e fade/slide suaves.
+ */
+declare function Sidebar({ menu, activeKey, header, footer, ariaLabel, children, className, mobileTitle, }: SidebarProps): react.JSX.Element;
+
+interface TopbarProps {
+    /**
+     * Logo exibido à esquerda. Aceita a string `"myeduzz"` (renderiza o logo
+     * oficial do MyEduzz), um `LogoConfig` ou qualquer `ReactNode`.
+     * Ignorado quando `application` é informado.
+     */
+    logo?: ReactNode | LogoConfig;
+    /**
+     * Identificador de um aplicativo da Eduzz (ex.: `"orbita"`). Busca o app no
+     * `applications.json` e renderiza o logo + nome dele (no mobile, só o logo),
+     * linkando para a URL do app. Tem precedência sobre `logo`.
+     */
+    application?: string;
+    apps?: AppsSource;
+    search?: ReactNode;
+    actions?: ReactNode;
+    user?: UserConfig;
+    showThemeToggle?: boolean;
+    /** Exibe o botão de menu (hambúrguer) no mobile. Padrão: `true`. */
+    showMenuButton?: boolean;
+    appsLabel?: string;
+    menuButtonLabel?: string;
+    className?: string;
+}
+/** Barra superior fixa: marca à esquerda, busca opcional ao centro, ações/usuário à direita. */
+declare function Topbar({ logo, application, apps, search, actions, user, showThemeToggle, showMenuButton, appsLabel, menuButtonLabel, className, }: TopbarProps): react.JSX.Element;
+
+/**
+ * Shell de aplicação composável. Forneça os subcomponentes como filhos —
+ * cada um com suas próprias props.
+ *
+ * @example
+ * import { RootzzLayout } from 'rootzz-layout';
+ * import 'rootzz-layout/styles.css';
+ *
+ * <RootzzLayout>
+ *   <RootzzLayout.Topbar
+ *     logo={{ src: '/logo.svg', alt: 'MyEduzz', href: '/' }}
+ *     apps
+ *     showThemeToggle
+ *     user={{ name: 'Designers da Eduzz', initials: 'Dd', menu: [{ label: 'Sair', danger: true }] }}
+ *   />
+ *   <RootzzLayout.Sidebar
+ *     activeKey="resumo"
+ *     menu={[
+ *       { key: 'resumo', label: 'Resumo', href: '/' },
+ *       { type: 'group', key: 'vendas', label: 'Vendas', items: [{ key: 'pedidos', label: 'Pedidos', href: '/pedidos' }] },
+ *     ]}
+ *   />
+ *   <RootzzLayout.Content>conteúdo aqui</RootzzLayout.Content>
+ * </RootzzLayout>
+ *
+ * Config de nível de shell (tema, linkComponent) fica no `<RootzzLayout>`:
+ * `<RootzzLayout theme="dark" linkComponent={Link}>…</RootzzLayout>`
+ */
+declare function RootzzLayoutBase({ children, theme, defaultTheme, onThemeChange, linkComponent, className, style, id, }: RootzzLayoutProps): react.JSX.Element;
+/**
+ * `RootzzLayout` + subcomponentes anexados:
+ * `RootzzLayout.Topbar`, `RootzzLayout.Sidebar`, `RootzzLayout.Content`.
+ * (Os mesmos componentes também são exportados individualmente.)
+ */
+declare const RootzzLayout: typeof RootzzLayoutBase & {
+    Topbar: typeof Topbar;
+    Sidebar: typeof Sidebar;
+    Content: typeof Content;
+};
+
+interface BrandProps {
+    /**
+     * Logo da topbar. Aceita:
+     * - a string `"myeduzz"` → renderiza o logo oficial do MyEduzz;
+     * - um `LogoConfig` (`{ src, alt, href… }`) → imagem configurável;
+     * - qualquer `ReactNode` → renderizado como veio.
+     *
+     * Ignorado quando `application` resolve um app.
+     */
+    logo?: ReactNode | LogoConfig;
+    /**
+     * Identificador de um aplicativo da Eduzz (campo `application` do
+     * `applications.json`, ex.: `"orbita"`). Busca o app na lista oficial e
+     * renderiza o logo + nome dele, linkando para a `url` do app.
+     * No mobile, mostra apenas o logo (sem o nome). Tem precedência sobre `logo`.
+     */
+    application?: string;
+    apps?: AppsSource;
+    appsLabel?: string;
+}
+/** Bloco da esquerda da topbar: botão de aplicativos + logo/aplicação. */
+declare function Brand({ logo, application, apps, appsLabel }: BrandProps): react.JSX.Element;
+
+interface AppsMenuProps {
+    /** Fonte dos apps (veja {@link AppsSource}). */
+    source?: AppsSource;
+    /** Rótulo acessível do botão. Padrão: "Aplicativos". */
+    label?: string;
+    /** Título exibido no topo do painel. Padrão: "Aplicativos". */
+    title?: string;
+}
+/** Botão de grade 9-pontos que abre o menu de aplicativos da Eduzz. */
+declare function AppsMenu({ source, label, title }: AppsMenuProps): react.JSX.Element | null;
+
+interface SearchBarProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'size'> {
+    /** Texto de placeholder. */
+    placeholder?: string;
+    /** Dica de atalho exibida à direita (ex.: "⌘K"). */
+    shortcut?: ReactNode;
+    /** Classe extra do wrapper. */
+    wrapperClassName?: string;
+}
+/**
+ * Campo de busca estilizado para o centro da topbar (opcional).
+ * É um `<input>` comum — controle via `value`/`onChange` como qualquer input.
+ */
+declare const SearchBar: react.ForwardRefExoticComponent<SearchBarProps & react.RefAttributes<HTMLInputElement>>;
+
+interface UserMenuProps {
+    user: UserConfig;
+}
+/** Usuário à direita da topbar: avatar + nome + dropdown de ações. */
+declare function UserMenu({ user }: UserMenuProps): react.JSX.Element;
+
+interface ThemeToggleProps {
+    /** Rótulo acessível. Padrão: "Alternar tema". */
+    label?: string;
+}
+/** Botão de alternância de tema (claro/escuro), com crossfade dos ícones. */
+declare function ThemeToggle({ label }: ThemeToggleProps): react.JSX.Element;
+
+interface SidebarItemProps {
+    item: MenuLink;
+    /** Recuo extra (usado para itens dentro de grupos). */
+    nested?: boolean;
+}
+/** Item simples (link) da sidebar, com estado ativo. */
+declare function SidebarItem({ item, nested }: SidebarItemProps): react.JSX.Element;
+
+interface SidebarGroupProps {
+    group: MenuGroup;
+}
+/** Grupo colapsável da sidebar (label em maiúsculas + chevron animado + altura animada). */
+declare function SidebarGroup({ group }: SidebarGroupProps): react.JSX.Element;
+
+interface DropdownTriggerArgs {
+    open: boolean;
+    toggle: () => void;
+    /** Props a serem espalhadas no elemento de trigger (acessibilidade). */
+    triggerProps: {
+        'aria-haspopup': 'menu';
+        'aria-expanded': boolean;
+        'aria-controls': string;
+    };
+}
+interface DropdownProps {
+    /** Renderiza o gatilho. Receba `toggle` e `triggerProps`. */
+    renderTrigger: (args: DropdownTriggerArgs) => ReactNode;
+    /** Conteúdo do painel. */
+    children: ReactNode;
+    /** Alinhamento horizontal do painel. Padrão: `'end'`. */
+    align?: 'start' | 'end';
+    /** Classe extra do painel. */
+    panelClassName?: string;
+    /** Largura do painel (px ou CSS). */
+    panelWidth?: number | string;
+    /** Fecha o painel ao clicar em qualquer lugar dentro dele. Padrão: `true`. */
+    closeOnContentClick?: boolean;
+    /** Rótulo acessível do menu. */
+    ariaLabel?: string;
+    /** Estado controlado (opcional). */
+    open?: boolean;
+    onOpenChange?: (open: boolean) => void;
+}
+/**
+ * Dropdown inline (sem portal — garante herança do escopo de estilo `.rootzz-layout`).
+ * Fecha em clique fora / Escape e faz fade in/out suave.
+ */
+declare function Dropdown({ renderTrigger, children, align, panelClassName, panelWidth, closeOnContentClick, ariaLabel, open: openProp, onOpenChange, }: DropdownProps): react.JSX.Element;
+
+interface OverlayProps {
+    open: boolean;
+    onClick?: () => void;
+    className?: string;
+}
+/** Camada escura semitransparente (mobile), com fade in/out. */
+declare function Overlay({ open, onClick, className }: OverlayProps): react.JSX.Element | null;
+
+interface IconButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+    /** Ícone/conteúdo central. */
+    children: ReactNode;
+    /** Conteúdo do badge (número ou nó). `true` exibe um ponto. */
+    badge?: ReactNode | boolean;
+    /** Tamanho do botão em px. Padrão: 40. */
+    size?: number;
+}
+/**
+ * Botão de ícone padronizado para a topbar (hover suave, foco acessível, badge opcional).
+ * Útil também para montar suas próprias ações custom mantendo a consistência visual.
+ */
+declare const IconButton: react.ForwardRefExoticComponent<IconButtonProps & react.RefAttributes<HTMLButtonElement>>;
+
+interface LayoutContextValue {
+    /** Tema atual. */
+    theme: ThemeMode;
+    /** Define o tema. */
+    setTheme: (theme: ThemeMode) => void;
+    /** Alterna entre claro e escuro. */
+    toggleTheme: () => void;
+    /** Drawer mobile aberto? */
+    mobileOpen: boolean;
+    /** Abre/fecha o drawer mobile. */
+    setMobileOpen: (open: boolean) => void;
+    /** Estamos em viewport mobile? */
+    isMobile: boolean;
+    /** Componente de link usado na navegação (padrão `<a>`). */
+    linkComponent: LinkComponent;
+}
+/** Acessa o estado do layout (tema, drawer mobile, etc.). */
+declare function useLayout(): LayoutContextValue;
+interface LayoutProviderProps {
+    children: ReactNode;
+    theme?: ThemeMode;
+    defaultTheme?: ThemeMode;
+    onThemeChange?: (theme: ThemeMode) => void;
+    linkComponent?: LinkComponent;
+}
+declare function LayoutProvider({ children, theme: themeProp, defaultTheme, onThemeChange, linkComponent, }: LayoutProviderProps): react.JSX.Element;
+
+/** URL padrão da lista de aplicativos da Eduzz. */
+declare const DEFAULT_APPS_URL = "https://cdn.eduzzcdn.com/topbar/applications.json";
+interface UseAppsResult {
+    items: AppItem[];
+    loading: boolean;
+    error: Error | null;
+}
+/**
+ * Resolve a fonte de apps em `{ items, loading, error }`.
+ * Listas estáticas são usadas direto; URLs são buscadas (com cache).
+ */
+declare function useApps(source: AppsSource | undefined): UseAppsResult;
+interface UseApplicationResult {
+    /** App encontrado pelo identificador, ou `null` enquanto carrega / se não existir. */
+    app: AppItem | null;
+    loading: boolean;
+    error: Error | null;
+}
+/**
+ * Resolve um único aplicativo da Eduzz pelo seu identificador (campo
+ * `application` do `applications.json`). Reaproveita o mesmo fetch/cache de
+ * {@link useApps}, então não há requisição extra quando o menu de apps já carregou.
+ *
+ * @param application Identificador (ex.: `"orbita"`). `undefined` desativa.
+ * @param url Fonte custom do JSON. Padrão: {@link DEFAULT_APPS_URL}.
+ */
+declare function useApplication(application: string | undefined, url?: string): UseApplicationResult;
+
+/**
+ * Concatena classes condicionalmente. Substituto mínimo de `clsx` para manter
+ * a biblioteca sem dependências de runtime.
+ *
+ * @example cx('rootzz-item', isActive && 'rootzz-item--active', { 'rootzz-hidden': hidden })
+ */
+type ClassValue = string | number | null | false | undefined | ClassValue[] | Record<string, boolean | null | undefined>;
+declare function cx(...inputs: ClassValue[]): string;
+
+export { type AppItem, AppsMenu, type AppsMenuProps, type AppsSource, Brand, type BrandProps, Content, type ContentProps, DEFAULT_APPS_URL, Dropdown, type DropdownProps, type DropdownTriggerArgs, IconButton, type IconButtonProps, type LayoutContextValue, LayoutProvider, type LayoutProviderProps, type LinkComponent, type LogoConfig, type MenuDivider, type MenuGroup, type MenuItem, type MenuLink, Overlay, type OverlayProps, RootzzLayout, type RootzzLayoutProps, SearchBar, type SearchBarProps, Sidebar, SidebarGroup, type SidebarGroupProps, SidebarItem, type SidebarItemProps, type SidebarProps, type ThemeMode, ThemeToggle, type ThemeToggleProps, Topbar, type TopbarProps, type UseApplicationResult, type UseAppsResult, type UserConfig, UserMenu, type UserMenuDivider, type UserMenuEntry, type UserMenuItem, type UserMenuProps, cx, useApplication, useApps, useLayout };