npm - @saitec/ui - Versions diffs - 0.1.0 → 0.1.2 - Mend

@saitec/ui 0.1.0 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (2) hide show

package/README.md +510 -64
package/package.json +5 -1

package/README.md CHANGED Viewed

@@ -1,64 +1,510 @@
-# Ui
-This project was generated using [Angular CLI](https://github.com/angular/angular-cli) version 22.1.0.
-## Code scaffolding
-Angular CLI includes powerful code scaffolding tools. To generate a new component, run:
-```bash
-ng generate component component-name
-```
-For a complete list of available schematics (such as `components`, `directives`, or `pipes`), run:
-```bash
-ng generate --help
-```
-## Building
-To build the library, run:
-```bash
-ng build ui
-```
-This command will compile your project, and the build artifacts will be placed in the `dist/` directory.
-### Publishing the Library
-Once the project is built, you can publish your library by following these steps:
-1. Navigate to the `dist` directory:
-   ```bash
-   cd dist/ui
-   ```
-2. Run the `npm publish` command to publish your library to the npm registry:
-   ```bash
-   npm publish
-   ```
-## Running unit tests
-To execute unit tests with the [Karma](https://karma-runner.github.io) test runner, use the following command:
-```bash
-ng test
-```
-## Running end-to-end tests
-For end-to-end (e2e) testing, run:
-```bash
-ng e2e
-```
-Angular CLI does not come with an end-to-end testing framework by default. You can choose one that suits your needs.
-## Additional Resources
-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.
+# @saitec/ui
+Reusable Angular UI component library developed by **SAITEC Ingeniería S.A.S.**
+`@saitec/ui` provides standalone Angular components, shared design tokens, light/dark themes, and reusable interaction patterns for SAITEC applications.
+The library is designed so consuming applications depend on the public `@saitec/ui/*` API instead of third-party component suites or internal source paths.
+## Features
+- Standalone Angular components
+- Angular Forms and `ControlValueAccessor` support
+- Signal-based APIs
+- Light and dark themes
+- CSS custom-property design tokens
+- Global, component, and instance-level customization
+- Angular CDK for overlay-based components where appropriate
+- No Tailwind dependency inside SUI
+- Secondary entry points such as `@saitec/ui/button` and `@saitec/ui/table`
+## Installation
+```bash
+npm install @saitec/ui
+```
+Some components use Angular CDK. If needed:
+```bash
+npm install @angular/cdk
+```
+Angular framework packages are provided by the consuming application.
+## Global styles
+Import SUI once from the application's global stylesheet:
+```css
+@import "@saitec/ui/styles.css";
+```
+If the application uses Tailwind:
+```css
+@import "tailwindcss";
+@import "@saitec/ui/styles.css";
+```
+SUI itself does not require Tailwind.
+## Basic usage
+```ts
+import { Component } from '@angular/core';
+import { SuiButton } from '@saitec/ui/button';
+import { SuiTag } from '@saitec/ui/tag';
+@Component({
+    selector: 'app-example',
+    standalone: true,
+    imports: [
+        SuiButton,
+        SuiTag
+    ],
+    template: `
+        <sui-button>
+            Save
+        </sui-button>
+        <sui-tag severity="success">
+            Active
+        </sui-tag>
+    `
+})
+export class ExampleComponent {
+}
+```
+## Secondary entry points
+Import components through their public package entry points:
+```ts
+import { SuiButton } from '@saitec/ui/button';
+import { SuiInput } from '@saitec/ui/input';
+import { SuiDialog } from '@saitec/ui/dialog';
+import { SuiTable, SuiColumn, SuiCell } from '@saitec/ui/table';
+```
+Shared types are exposed from:
+```ts
+import { SuiOption } from '@saitec/ui/core';
+```
+Do not import internal source files.
+Bad:
+```ts
+import { SuiButton } from '@saitec/ui/button/src/button.component';
+```
+Good:
+```ts
+import { SuiButton } from '@saitec/ui/button';
+```
+## Themes
+SUI uses the `data-theme` attribute.
+Light:
+```html
+<html data-theme="light">
+```
+Dark:
+```html
+<html data-theme="dark">
+```
+Runtime switch:
+```ts
+document.documentElement.setAttribute(
+    'data-theme',
+    'dark'
+);
+```
+SUI components consume semantic variables such as:
+```css
+--sui-color-background
+--sui-color-surface
+--sui-color-content
+--sui-color-border
+--sui-color-primary
+--sui-color-danger
+```
+Changing the theme updates those semantic values globally.
+## Design tokens
+The design-token system is organized into layers:
+```text
+Primitive tokens
+    ↓
+Theme semantic tokens
+    ↓
+Foundation tokens
+    ↓
+Component tokens
+    ↓
+Component CSS
+```
+Main files:
+```text
+src/lib/core/tokens/
+├── primitives.css
+├── foundations.css
+├── components.css
+└── components/
+    ├── button.css
+    ├── input.css
+    ├── table.css
+    └── ...
+src/lib/core/themes/
+├── light.css
+└── dark.css
+```
+### Primitive tokens
+Raw design values:
+```css
+--sui-palette-brand-600
+--sui-palette-neutral-900
+--sui-radius-md
+--sui-shadow-sm
+```
+### Semantic theme tokens
+Theme-level meaning:
+```css
+--sui-color-primary
+--sui-color-surface
+--sui-color-content
+--sui-color-success
+--sui-color-warning
+--sui-color-danger
+--sui-color-info
+```
+### Foundation tokens
+Shared control and layout values:
+```css
+--sui-control-height-md
+--sui-control-padding-x-md
+--sui-space-4
+--sui-focus-ring-width
+--sui-duration-normal
+--sui-z-dialog
+```
+### Component tokens
+Each component exposes its own styling contract:
+```css
+--sui-button-primary-background
+--sui-button-radius
+--sui-table-header-background
+--sui-dialog-background
+```
+## Customization
+### Global brand customization
+```css
+:root {
+    --sui-color-primary: #0057b8;
+    --sui-color-primary-hover: #004a9d;
+    --sui-color-primary-active: #003d82;
+}
+```
+### Component-level customization
+```css
+:root {
+    --sui-button-radius: 9999px;
+}
+```
+### Single-instance customization
+```html
+<sui-button class="special-button">
+    Save
+</sui-button>
+```
+```css
+.special-button {
+    --sui-button-primary-background: #7c3aed;
+    --sui-button-primary-background-hover: #6d28d9;
+    --sui-button-radius: 0;
+}
+```
+This avoids `::ng-deep` and keeps consumers independent from internal component markup.
+## Forms
+Form controls implement Angular `ControlValueAccessor` where appropriate.
+```html
+<sui-input
+    formControlName="customerName"
+    placeholder="Customer name">
+</sui-input>
+```
+## Shared options
+Selection components share a common option contract:
+```ts
+import { SuiOption } from '@saitec/ui/core';
+const countries: SuiOption<string>[] = [
+    {
+        label: 'Colombia',
+        value: 'CO'
+    },
+    {
+        label: 'Ecuador',
+        value: 'EC'
+    },
+    {
+        label: 'Peru',
+        value: 'PE'
+    }
+];
+```
+The same collection can be used with components such as:
+```html
+<sui-select [options]="countries" />
+<sui-autocomplete [options]="countries" />
+<sui-multiselect [options]="countries" />
+```
+## Table
+```ts
+import {
+    SuiCell,
+    SuiColumn,
+    SuiTable
+} from '@saitec/ui/table';
+import {
+    SuiTag
+} from '@saitec/ui/tag';
+```
+```html
+<sui-table
+    [value]="products"
+    [striped]="true"
+    [hoverable]="true">
+    <sui-column
+        field="code"
+        header="Product"
+        [sortable]="true">
+    </sui-column>
+    <sui-column
+        field="weight"
+        header="Weight"
+        align="right"
+        [sortable]="true">
+    </sui-column>
+    <sui-column
+        field="status"
+        header="Status">
+        <ng-template
+            suiCell
+            let-value="value">
+            <sui-tag severity="success">
+                {{ value }}
+            </sui-tag>
+        </ng-template>
+    </sui-column>
+</sui-table>
+```
+When using `suiCell`, remember to import `SuiCell`.
+## Toast and confirm
+Place one instance near the root of the application:
+```html
+<router-outlet />
+<sui-toast />
+<sui-confirm />
+```
+Then inject the corresponding service:
+```ts
+private readonly toast =
+    inject(SuiToastService);
+private readonly confirm =
+    inject(SuiConfirmService);
+```
+## File upload
+`SuiFileUpload` manages file selection and UI behavior. HTTP upload remains the responsibility of the consuming application.
+```html
+<sui-file-upload
+    [multiple]="true"
+    accept=".pdf,.png,.jpg"
+    [maxFileSize]="10 * 1024 * 1024"
+    (filesChange)="files = $event">
+</sui-file-upload>
+```
+## Available components
+| Category | Components |
+| --- | --- |
+| Form | FormField, Input, Textarea, Checkbox, ToggleSwitch, InputNumber, DatePicker |
+| Selection | Select, Autocomplete, MultiSelect |
+| Actions | Button |
+| Data | Table |
+| Navigation | Menu, Menubar, Tabs |
+| Status | Badge, Tag, Message, ProgressSpinner |
+| Containers | Card, Panel, Fieldset, Toolbar, Divider |
+| Overlay | Dialog, Drawer, Tooltip, Toast, Confirm |
+| Files | FileUpload |
+| Content | Chip |
+## Development
+Build the library in watch mode:
+```bash
+ng build ui --watch --configuration development
+```
+Run the showcase separately:
+```bash
+ng serve showcase
+```
+Production build:
+```bash
+ng build ui --configuration production
+```
+The distributable package is generated under:
+```text
+dist/ui
+```
+## Publishing
+Publish the compiled package, not `projects/ui`.
+```bash
+ng build ui --configuration production
+cd dist/ui
+npm publish --dry-run --access public
+npm publish --access public
+```
+The version must be incremented before publishing another release.
+Recommended versioning while the API is still evolving:
+```text
+0.1.x
+```
+Then move to `1.0.0` when the public API is considered stable.
+## Architecture guidelines
+When adding components:
+1. Expose a small application-focused API instead of cloning a third-party component API.
+2. Prefer native HTML semantics when they already provide good accessibility and behavior.
+3. Use Angular CDK where robust overlay, focus, or positioning infrastructure is needed.
+4. Implement `ControlValueAccessor` for form controls.
+5. Keep Angular components standalone.
+6. Prefer signals for inputs, models, outputs, and internal state where appropriate.
+7. Reuse shared contracts such as `SuiOption<T>`.
+8. Keep visual design decisions in design tokens.
+9. Keep component CSS focused on layout, structure, and state behavior.
+10. Never require consuming applications to import internal source paths.
+## Styling rule
+A core SUI rule is:
+> Component CSS describes how a component behaves and is laid out. Design tokens describe what it looks like.
+Prefer:
+```css
+.sui-button--primary {
+    background-color:
+        var(--sui-button-primary-background);
+    color:
+        var(--sui-button-primary-text);
+}
+```
+instead of:
+```css
+.sui-button--primary {
+    background-color: #2563eb;
+    color: #ffffff;
+}
+```
+## License
+Maintained by **SAITEC Ingeniería S.A.S.**
+Set the package `license` field and this section according to the distribution model selected for the library.

package/package.json CHANGED Viewed

@@ -1,7 +1,11 @@
 {
   "name": "@saitec/ui",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "SAITEC Angular UI component library",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/saitec-ingenieria/saitec-ui.git"
+  },
   "license": "UNLICENSED",
   "publishConfig": {
     "access": "public"