@juligc99/loro-ui 0.0.8 → 0.0.13

package/README.md

@@ -1,66 +1,164 @@
-# LoroUi
+# Loro UI
 
-This project was generated using [Angular CLI](https://github.com/angular/angular-cli) version 21.2.0.
+Loro UI is the Angular design system for Al Loro. It contains standalone Angular components, design tokens, icons, images, Storybook documentation and npm publishing configuration.
 
-## Code scaffolding
+## Requirements
 
-Angular CLI includes powerful code scaffolding tools. To generate a new component, run:
+- Node `20.19+`, `22.12+` or `24+`
+- npm `10.9+`
+- Angular `21+`
+
+Node 22 LTS is recommended for local Storybook work.
+
+## Install dependencies
 
 ```bash
-ng generate component component-name
+npm install
 ```
 
-For a complete list of available schematics (such as `components`, `directives`, or `pipes`), run:
+## Development
 
 ```bash
-ng generate --help
+npm run build:loro-ui
+npm run storybook
 ```
 
-## Building
+Stable Storybook run with cache cleanup:
+
+```bash
+npm run storybook:stable
+```
 
-To build the library, run:
+Build static Storybook:
 
 ```bash
-ng build loro-ui
+npm run build-storybook:stable
 ```
 
-This command will compile your project, and the build artifacts will be placed in the `dist/` directory.
+## Package structure
+
+```txt
+projects/loro-ui/
+├── .storybook/
+├── scripts/
+├── src/
+│   ├── lib/assets/
+│   ├── lib/components/
+│   ├── lib/design-tokens/
+│   ├── lib/docs/
+│   ├── lib/services/
+│   ├── lib/styles/
+│   ├── public-api.ts
+│   └── styles.scss
+├── ng-package.json
+├── package.json
+└── tsconfig.storybook.json
+```
+
+## Angular best practices used
 
-### Publishing the Library
+- Standalone components.
+- Signal inputs/models.
+- `ChangeDetectionStrategy.OnPush`.
+- `@angular/forms/signals` support for reusable form controls.
+- Public API through `projects/loro-ui/src/public-api.ts`.
+- Relative internal imports to avoid broken npm bundles.
+- Sass tokens exported as package assets.
 
-Once the project is built, you can publish your library by following these steps:
+## Sass API
 
-1. Navigate to the `dist` directory:
+Use breakpoints from the package:
 
-   ```bash
-   cd dist/loro-ui
-   ```
+```scss
+@use '@juligc99/loro-ui/styles/breakpoints' as bp;
+```
 
-2. Run the `npm publish` command to publish your library to the npm registry:
-   ```bash
-   npm publish
-   ```
+Use theme tokens globally in an app:
 
-4194ceb188576bc286d666413ed1d95a86034d43bb196f536a59fa97b431c32c
+```scss
+@use 'sass:meta';
 
-## Running unit tests
+@include meta.load-css('@juligc99/loro-ui/design-tokens/loro-theme.scss');
+```
 
-To execute unit tests with the [Karma](https://karma-runner.github.io) test runner, use the following command:
+Copy package assets in the consuming Angular app if you use images/fonts/icons by path:
+
+```json
+{
+  "glob": "**/*",
+  "input": "node_modules/@juligc99/loro-ui/assets/loro-ui",
+  "output": "/assets/loro-ui"
+}
+```
+
+## Publish to npm
+
+The workspace root is private and must not be published. The publishable package is generated in `dist/loro-ui`.
 
 ```bash
-ng test
+npm login
+npm run publish:loro-ui:dry
+npm run publish:loro-ui
 ```
 
-## Running end-to-end tests
+Manual flow:
 
-For end-to-end (e2e) testing, run:
+```bash
+npm run build:loro-ui
+cd dist/loro-ui
+npm publish --dry-run
+npm publish --access public
+```
+
+## Versioning
 
 ```bash
-ng e2e
+npm run version:loro-ui:patch
+npm run publish:loro-ui
 ```
 
-Angular CLI does not come with an end-to-end testing framework by default. You can choose one that suits your needs.
+The current package version is `0.0.11`.
 
-## Additional Resources
+## Consume from an Angular app
 
-For more information on using the Angular CLI, including detailed command references, visit the [Angular CLI Overview and Command Reference](https://angular.dev/tools/cli) page.
+```bash
+npm i @juligc99/loro-ui
+```
+
+```ts
+import { LoroButton, LoroInput } from '@juligc99/loro-ui';
+```
+
+```ts
+@Component({
+  standalone: true,
+  imports: [LoroButton, LoroInput],
+  template: `
+    <loro-button label="Guardar" />
+    <loro-input label="Email" type="email" />
+  `,
+})
+export class ExampleComponent {}
+```
+
+## Quality checks
+
+```bash
+npm run lint:all
+npm run verify
+```
+
+
+## Form controls
+
+Form components that represent values implement Angular Signal Forms control contracts:
+
+- `LoroInput`, `LoroAuthField`, `LoroTextArea`, `LoroDropdown`, `LoroSegmentedControl`: `FormValueControl<string>`.
+- `LoroCheckbox`, `LoroToggle`: `FormCheckboxControl`.
+
+Use them from an app with `FormField` from `@angular/forms/signals`:
+
+```html
+<loro-input [formField]="form.email" label="Email" type="email" />
+<loro-checkbox [formField]="form.acceptTerms">Acepto los términos</loro-checkbox>
+```