@agroshine/ags-web-ui-kit

Librería oficial de componentes React de AgroShine. Atomic Design, design tokens semánticos y primitives accesibles sobre Radix + shadcn/ui.

✨ Características

• Atomic Design completo: atoms, molecules, organisms, ui (primitives), hooks y lib.
• Tipado estricto con TypeScript y .d.ts por subpath export.
• Build dual ESM + CJS generado con tsup, tree-shakeable.
• Tailwind v4 first-class: preset compartido + tokens semánticos como @theme CSS.
• Accesibilidad apoyada en Radix UI y patrones shadcn/ui.
• Iconografía con lucide-react y soporte opcional de FontAwesome.
• Storybook 8 para documentación viva y QA visual.
• Semantic Release + Conventional Commits → versionado y CHANGELOG.md automáticos.

📦 Stack

React 18/19 · TypeScript 5.6 · Tailwind CSS v4 · shadcn/ui · Radix UI · class-variance-authority · tailwind-merge · clsx · lucide-react · date-fns / dayjs · sonner.

📑 Tabla de contenido

• Instalación
• Configuración de Tailwind
• Uso
• Estructura del proyecto
• Componentes
• Scripts
• Storybook
• Convenciones de commits
• Release y publicación
• Compatibilidad
• Licencia

🚀 Instalación

Desde npm (público)

pnpm add @agroshine/ags-web-ui-kit
# o
npm install @agroshine/ags-web-ui-kit
# o
yarn add @agroshine/ags-web-ui-kit

Como dependencia de workspace (admin · client · website)

// package.json del consumidor
{
  "dependencies": {
    "@agroshine/ags-web-ui-kit": "workspace:*"
  }
}

pnpm install
pnpm --filter @agroshine/ags-web-ui-kit build

Peer dependencies

La librería declara como peerDependencies el ecosistema React + Radix + Tailwind. pnpm / npm@7+ los instala automáticamente; revisa package.json si necesitas anclar versiones específicas. Algunos peers son opcionales (FontAwesome, sonner, react-day-picker, date-fns, dayjs) y solo son necesarios si usas el componente correspondiente.

🎨 Configuración de Tailwind

Tailwind v3 (preset clásico)

// tailwind.config.{js,ts}
module.exports = {
  presets: [require('@agroshine/ags-web-ui-kit/tailwind.preset')],
  content: [
    './src/**/*.{ts,tsx}',
    './node_modules/@agroshine/ags-web-ui-kit/dist/**/*.{js,cjs}',
  ],
};

Tailwind v4 (CSS-first, recomendado)

/* src/index.css */
@import 'tailwindcss';
@import '@agroshine/ags-web-ui-kit/styles/tokens.css';

tokens.css expone los tokens semánticos AgroShine (--color-brand-*, --color-surface-*, --radius-*, etc.) como bloque @theme, listos para utilidades arbitrarias y cn().

🧩 Uso

Import raíz (recomendado)

import { Button, Tag, Drawer, useModal } from '@agroshine/ags-web-ui-kit';

export function Demo() {
  return (
    <Button variant="primary" size="md">
      Iniciar cosecha
    </Button>
  );
}

Imports por categoría (para tree-shaking quirúrgico)

import { Button, Input } from '@agroshine/ags-web-ui-kit/atoms';
import { Modal, Table }  from '@agroshine/ags-web-ui-kit/molecules';
import { Layout, Sidebar } from '@agroshine/ags-web-ui-kit/organisms';
import { useDrawer }     from '@agroshine/ags-web-ui-kit/hooks';
import { cn }            from '@agroshine/ags-web-ui-kit/lib';

Acceso a primitives shadcn/Radix

Los primitives no se reexportan desde el barrel raíz para evitar colisiones con sus wrappers AgroShine. Si los necesitas crudos:

import { Avatar as AvatarRoot, Tabs as TabsRoot } from '@agroshine/ags-web-ui-kit/ui';

🗂 Estructura del proyecto

src/
├── ui/          shadcn-style primitives (button, dialog, sheet, dropdown-menu, …)
├── atoms/       Button, Input, Tag, Spinner, Checkbox, Radio, Select, Switch, …
├── molecules/   Drawer, Modal, Table, Steps, Tabs, Card, Alert, Tooltip, …
├── organisms/   Layout, Sidebar, Header, PageHeader, FormCard, SearchFilterBar, …
├── hooks/       useDrawer, useModal, usePagination, useResponsive, useSearch
├── lib/         cn() y utilidades compartidas
├── styles/      tokens.css (design tokens semánticos)
└── foundation/  Stories de tipografía, color y feedback (Storybook)

🧱 Componentes

Avatar · Button · Checkbox · Descriptions · Dropdown · FormItem · Input · InputNumber · Pagination · Progress · Radio · Rate · Select · Separator · Skeleton · Slider · Spinners · Switch · Tag · Textarea · Toggle · ToggleGroup

Alert · Breadcrumb · Card · Drawer · Empty · HoverCard · List · Modal · Popconfirm · Popover · Segmented · Statistic · Steps · Table · Tabs · Timeline · Tooltip

Accordion · Content · FormCard · Header · Layout · PageHeader · Picker · QueryState · Result · SearchFilterBar · Sidebar · Toaster · Tree

useDrawer · useModal · usePagination · useResponsive · useSearch

🛠 Scripts

| Script | Descripción | |---|---| | pnpm build | Build dual ESM + CJS con tsup (incluye .d.ts y tokens.css). | | pnpm dev | Watch mode de tsup para desarrollo local. | | pnpm typecheck | tsc --noEmit sobre todo el proyecto. | | pnpm lint / pnpm lint:fix | Lint con ESLint 9 (flat config). | | pnpm format / pnpm format:check | Prettier. | | pnpm storybook | Levanta Storybook en http://localhost:6006. | | pnpm build-storybook | Build estático de Storybook → storybook-static/. | | pnpm commit | Asistente interactivo de Commitizen (cz-customizable). | | pnpm release | Lanza semantic-release (uso reservado a CI). | | pnpm clean | Elimina dist/. |

📖 Storybook

Storybook 8 cubre los tres niveles atómicos y stories de foundation (color, tipografía, feedback).

pnpm storybook

El build estático se publica desde CI a partir de storybook-static/.

✍️ Convenciones de commits

Este repo aplica Conventional Commits mediante commitlint + husky. Para evitar errores usa el asistente:

pnpm commit

Tipos habituales: feat, fix, perf, refactor, docs, test, build, ci, chore, style, revert. Los scopes sugeridos están definidos en .cz-config.js (atoms, molecules, organisms, ui, hooks, tokens, build, ci, …).

Los commits que no respeten el formato son rechazados por el hook commit-msg.

🚢 Release y publicación

El versionado lo maneja semantic-release desde GitHub Actions, en función del tipo de commits agregados a main:

• feat: → minor
• fix: / perf: → patch
• BREAKING CHANGE: (footer) → major

El pipeline:

1. Calcula la próxima versión a partir del log.
2. Actualiza package.json, CHANGELOG.md y version.
3. Publica en npm (@agroshine/ags-web-ui-kit, access: public).
4. Crea release y tag en GitHub.

No publiques manualmente. Mergea a main y deja correr el workflow.

✅ Compatibilidad

| Runtime | Versión | |---|---| | Node | 20.x | | pnpm | 10.x | | React | 18.x o 19.x | | Tailwind CSS | v4.x (compatible con v3 vía preset) | | TypeScript | ~5.6 |

📄 Licencia

MIT © AgroShine