@keepui/ui 0.1.0

package/README.md

@@ -0,0 +1,267 @@
+# KeepUI
+
+> Angular cross-platform UI component library with optional Capacitor support.
+
+[![npm version](https://img.shields.io/npm/v/@keepui/ui.svg)](https://www.npmjs.com/package/@keepui/ui)
+[![license](https://img.shields.io/npm/l/@keepui/ui.svg)](LICENSE)
+
+---
+
+## Purpose
+
+KeepUI is a reusable Angular component library designed to work seamlessly across:
+
+- **Standard Angular web applications** (browser only)
+- **Angular + Capacitor applications** (iOS, Android, PWA)
+
+The library uses a **Port/Adapter pattern** to keep UI components fully decoupled from platform-specific APIs. Components never import `@capacitor/*` directly; they depend on an injected `FilePort` interface. Concrete implementations are registered via functional providers.
+
+---
+
+## Package Structure
+
+| Package | Description |
+|---|---|
+| `@keepui/ui` | Core components, ports, tokens, web adapter |
+| `@keepui/ui/capacitor` | Capacitor adapter — use *instead of* the web provider |
+
+---
+
+## Installation
+
+```bash
+# Using ng add (recommended):
+ng add @keepui/ui
+
+# Or manually:
+npm install @keepui/ui
+```
+
+For Capacitor support (optional):
+
+```bash
+npm install @capacitor/core @capacitor/camera
+npx cap sync
+```
+
+---
+
+## Usage — Angular Web App
+
+### 1. Register the web provider
+
+```ts
+// src/app/app.config.ts
+import { ApplicationConfig } from '@angular/core';
+import { provideKeepUi } from '@keepui/ui';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideKeepUi(),
+    // ...other providers
+  ],
+};
+```
+
+### 2. Use components
+
+```ts
+// src/app/app.component.ts
+import { Component } from '@angular/core';
+import {
+  ButtonComponent,
+  CardComponent,
+  ImagePreviewComponent,
+} from '@keepui/ui';
+
+@Component({
+  selector: 'app-root',
+  standalone: true,
+  imports: [ButtonComponent, CardComponent, ImagePreviewComponent],
+  template: `
+    <keepui-card>
+      <h2>Image Picker</h2>
+      <keepui-image-preview />
+    </keepui-card>
+
+    <keepui-button (clicked)="greet()">Hello</keepui-button>
+  `,
+})
+export class AppComponent {
+  greet() {
+    alert('Hello from KeepUI!');
+  }
+}
+```
+
+---
+
+## Usage — Angular + Capacitor App
+
+### 1. Register the Capacitor provider
+
+```ts
+// src/app/app.config.ts
+import { ApplicationConfig } from '@angular/core';
+import { provideKeepUiCapacitor } from '@keepui/ui/capacitor';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideKeepUiCapacitor(),
+    // ...other providers
+  ],
+};
+```
+
+> **Note:** Use `provideKeepUiCapacitor()` **instead of** `provideKeepUi()` — never both.
+
+### 2. Use the same components
+
+```ts
+// src/app/app.component.ts — IDENTICAL to the web example above
+import { ImagePreviewComponent } from '@keepui/ui';
+```
+
+The component is unchanged. Only the provider differs.
+
+---
+
+## Available Components
+
+### `<keepui-button>`
+
+```html
+<keepui-button (clicked)="doSomething()">Click me</keepui-button>
+<keepui-button [disabled]="isLoading" type="submit">Submit</keepui-button>
+```
+
+| Input | Type | Default | Description |
+|---|---|---|---|
+| `disabled` | `boolean` | `false` | Disables the button |
+| `type` | `'button' \| 'submit' \| 'reset'` | `'button'` | HTML type attribute |
+
+| Output | Type | Description |
+|---|---|---|
+| `clicked` | `void` | Emitted on click |
+
+### `<keepui-card>`
+
+```html
+<keepui-card [elevation]="2">
+  <p>Card content</p>
+</keepui-card>
+```
+
+| Input | Type | Default | Description |
+|---|---|---|---|
+| `elevation` | `0 \| 1 \| 2 \| 3` | `1` | Shadow depth |
+
+### `<keepui-image-preview>`
+
+```html
+<keepui-image-preview />
+```
+
+No inputs. Requires `FILE_PORT` to be provided (via `provideKeepUi()` or `provideKeepUiCapacitor()`).
+
+**Exposed signals (for advanced usage):**
+
+| Signal | Type | Description |
+|---|---|---|
+| `imageUrl` | `Signal<string \| null>` | URL of the selected image |
+| `error` | `Signal<string \| null>` | Error message if pick failed |
+| `loading` | `Signal<boolean>` | True while picking is in progress |
+
+---
+
+## Architecture Notes
+
+### Port/Adapter Pattern
+
+```
+ImagePreviewComponent
+       │
+       │ inject(FILE_PORT)
+       ▼
+   FilePort (interface)
+       │
+   ┌───┴───────────┐
+   │               │
+WebFileService  CapacitorFileService
+(browser input)  (@capacitor/camera)
+```
+
+- Components depend only on the `FilePort` interface via the `FILE_PORT` injection token.
+- `provideKeepUi()` registers `WebFileService`.
+- `provideKeepUiCapacitor()` registers `CapacitorFileService`.
+- Capacitor dependencies are **not** pulled into web builds.
+
+### Secondary Entrypoint
+
+The `@keepui/ui/capacitor` entrypoint is a secondary ng-packagr entrypoint within the same library project. It is compiled and published alongside the main package but kept in a separate entry so Capacitor dependencies are not required in web-only applications.
+
+---
+
+## Testing
+
+Use `MockFileService` in your tests:
+
+```ts
+import { MockFileService } from '@keepui/ui';
+import { FILE_PORT } from '@keepui/ui';
+
+TestBed.configureTestingModule({
+  imports: [ImagePreviewComponent],
+  providers: [{ provide: FILE_PORT, useClass: MockFileService }],
+});
+```
+
+`MockFileService` resolves by default. Set `nextError` to test error paths:
+
+```ts
+const mock = TestBed.inject(FILE_PORT) as MockFileService;
+mock.nextError = new Error('Camera cancelled');
+```
+
+---
+
+## Building
+
+```bash
+# Build for production (APF, partial compilation):
+npm run build
+
+# Build for development (without schematics):
+npm run build:dev
+
+# Build schematics only:
+npm run build:schematics
+
+# Run tests:
+npm test
+```
+
+The production build output is placed in `dist/keep-ui/` and follows Angular Package Format.
+
+---
+
+## Publishing to npm
+
+```bash
+npm run build
+cd dist/keep-ui
+npm publish --access public
+```
+
+Ensure `package.json` has the correct `name`, `version`, and `peerDependencies` before publishing.
+
+---
+
+## Future Improvements
+
+- Additional components (modal, toast, form controls, etc.)
+- More Capacitor adapters (Geolocation, Share, Haptics)
+- Theming support via CSS custom properties
+- Storybook integration
+- Automated publishing via GitHub Actions
+- E2E tests with Playwright

package/capacitor/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Generated bundle index. Do not edit.
+ */
+/// <amd-module name="@keepui/ui/capacitor" />
+export * from './public-api';
+//# sourceMappingURL=keepui-ui-capacitor.d.ts.map

package/capacitor/keepui-ui-capacitor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keepui-ui-capacitor.d.ts","sourceRoot":"","sources":["../../../projects/keep-ui/capacitor/src/keepui-ui-capacitor.ts"],"names":[],"mappings":"AAAA;;GAEG;;AAEH,cAAc,cAAc,CAAC"}

package/capacitor/lib/providers/provide-keep-ui-capacitor.d.ts

@@ -0,0 +1,22 @@
+import { EnvironmentProviders } from '@angular/core';
+/**
+ * Registers KeepUI providers for an **Angular + Capacitor** application.
+ *
+ * Registers `CapacitorFileService` as the implementation of `FILE_PORT`,
+ * enabling `ImagePreviewComponent` to use the device's native image picker.
+ *
+ * Add to `app.config.ts` **instead of** `provideKeepUi()`:
+ * ```ts
+ * import { provideKeepUiCapacitor } from '@keepui/ui/capacitor';
+ *
+ * export const appConfig: ApplicationConfig = {
+ *   providers: [provideKeepUiCapacitor()],
+ * };
+ * ```
+ *
+ * Prerequisites:
+ * - `@capacitor/camera` plugin installed and synced (`npx cap sync`)
+ * - Camera permissions declared in `AndroidManifest.xml` / `Info.plist`
+ */
+export declare function provideKeepUiCapacitor(): EnvironmentProviders;
+//# sourceMappingURL=provide-keep-ui-capacitor.d.ts.map

package/capacitor/lib/providers/provide-keep-ui-capacitor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provide-keep-ui-capacitor.d.ts","sourceRoot":"","sources":["../../../../../projects/keep-ui/capacitor/src/lib/providers/provide-keep-ui-capacitor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAA4B,MAAM,eAAe,CAAC;AAI/E;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,sBAAsB,IAAI,oBAAoB,CAI7D"}

package/capacitor/lib/services/capacitor-file.service.d.ts

@@ -0,0 +1,23 @@
+import { FilePort } from '@keepui/ui';
+import { FileResult } from '@keepui/ui';
+import * as i0 from "@angular/core";
+/**
+ * Capacitor implementation of `FilePort`.
+ *
+ * Uses `@capacitor/camera` to open the native image picker on iOS/Android, and
+ * falls back gracefully to the web camera on non-native platforms.
+ *
+ * The returned `dataUrl` is:
+ * - On native: the result of `Capacitor.convertFileSrc(photo.path)`, which
+ *   converts the native file path to an HTTP URL the WebView can display.
+ * - On web/PWA: `photo.webPath` as-is.
+ *
+ * This service has no dependency on `WebFileService`; it is a fully independent
+ * adapter registered by `provideKeepUiCapacitor()`.
+ */
+export declare class CapacitorFileService implements FilePort {
+    pickImage(): Promise<FileResult>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<CapacitorFileService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<CapacitorFileService>;
+}
+//# sourceMappingURL=capacitor-file.service.d.ts.map

package/capacitor/lib/services/capacitor-file.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capacitor-file.service.d.ts","sourceRoot":"","sources":["../../../../../projects/keep-ui/capacitor/src/lib/services/capacitor-file.service.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;;AAExC;;;;;;;;;;;;;GAaG;AACH,qBACa,oBAAqB,YAAW,QAAQ;IAC7C,SAAS,IAAI,OAAO,CAAC,UAAU,CAAC;yCAD3B,oBAAoB;6CAApB,oBAAoB;CAsBhC"}

package/capacitor/public-api.d.ts

@@ -0,0 +1,3 @@
+export * from './lib/services/capacitor-file.service';
+export * from './lib/providers/provide-keep-ui-capacitor';
+//# sourceMappingURL=public-api.d.ts.map

package/capacitor/public-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"public-api.d.ts","sourceRoot":"","sources":["../../../projects/keep-ui/capacitor/src/public-api.ts"],"names":[],"mappings":"AAEA,cAAc,uCAAuC,CAAC;AACtD,cAAc,2CAA2C,CAAC"}

package/fesm2022/keepui-ui-capacitor.mjs

@@ -0,0 +1,79 @@
+import * as i0 from '@angular/core';
+import { Injectable, makeEnvironmentProviders } from '@angular/core';
+import { Capacitor } from '@capacitor/core';
+import { Camera, CameraSource, CameraResultType } from '@capacitor/camera';
+import { FILE_PORT } from '@keepui/ui';
+
+/**
+ * Capacitor implementation of `FilePort`.
+ *
+ * Uses `@capacitor/camera` to open the native image picker on iOS/Android, and
+ * falls back gracefully to the web camera on non-native platforms.
+ *
+ * The returned `dataUrl` is:
+ * - On native: the result of `Capacitor.convertFileSrc(photo.path)`, which
+ *   converts the native file path to an HTTP URL the WebView can display.
+ * - On web/PWA: `photo.webPath` as-is.
+ *
+ * This service has no dependency on `WebFileService`; it is a fully independent
+ * adapter registered by `provideKeepUiCapacitor()`.
+ */
+class CapacitorFileService {
+    async pickImage() {
+        const photo = await Camera.getPhoto({
+            resultType: CameraResultType.Uri,
+            source: CameraSource.Photos,
+            quality: 90,
+        });
+        // `photo.path` is the native file path (only available on native platforms).
+        // `photo.webPath` is always available but may be undefined on some edge cases.
+        const rawPath = photo.path ?? photo.webPath ?? '';
+        // On a native Capacitor context, convert the native path to a WebView-friendly URL.
+        const dataUrl = Capacitor.isNativePlatform()
+            ? Capacitor.convertFileSrc(rawPath)
+            : rawPath;
+        return {
+            dataUrl,
+            mimeType: `image/${photo.format}`,
+        };
+    }
+    static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "19.2.20", ngImport: i0, type: CapacitorFileService, deps: [], target: i0.ɵɵFactoryTarget.Injectable }); }
+    static { this.ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "19.2.20", ngImport: i0, type: CapacitorFileService }); }
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "19.2.20", ngImport: i0, type: CapacitorFileService, decorators: [{
+            type: Injectable
+        }] });
+
+/**
+ * Registers KeepUI providers for an **Angular + Capacitor** application.
+ *
+ * Registers `CapacitorFileService` as the implementation of `FILE_PORT`,
+ * enabling `ImagePreviewComponent` to use the device's native image picker.
+ *
+ * Add to `app.config.ts` **instead of** `provideKeepUi()`:
+ * ```ts
+ * import { provideKeepUiCapacitor } from '@keepui/ui/capacitor';
+ *
+ * export const appConfig: ApplicationConfig = {
+ *   providers: [provideKeepUiCapacitor()],
+ * };
+ * ```
+ *
+ * Prerequisites:
+ * - `@capacitor/camera` plugin installed and synced (`npx cap sync`)
+ * - Camera permissions declared in `AndroidManifest.xml` / `Info.plist`
+ */
+function provideKeepUiCapacitor() {
+    return makeEnvironmentProviders([
+        { provide: FILE_PORT, useClass: CapacitorFileService },
+    ]);
+}
+
+// Public API Surface of @keepui/ui/capacitor
+
+/**
+ * Generated bundle index. Do not edit.
+ */
+
+export { CapacitorFileService, provideKeepUiCapacitor };
+//# sourceMappingURL=keepui-ui-capacitor.mjs.map

package/fesm2022/keepui-ui-capacitor.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"keepui-ui-capacitor.mjs","sources":["../../../projects/keep-ui/capacitor/src/lib/services/capacitor-file.service.ts","../../../projects/keep-ui/capacitor/src/lib/providers/provide-keep-ui-capacitor.ts","../../../projects/keep-ui/capacitor/src/public-api.ts","../../../projects/keep-ui/capacitor/src/keepui-ui-capacitor.ts"],"sourcesContent":["import { Injectable } from '@angular/core';\r\nimport { Capacitor } from '@capacitor/core';\r\nimport { Camera, CameraResultType, CameraSource } from '@capacitor/camera';\r\nimport { FilePort } from '@keepui/ui';\r\nimport { FileResult } from '@keepui/ui';\r\n\r\n/**\r\n * Capacitor implementation of `FilePort`.\r\n *\r\n * Uses `@capacitor/camera` to open the native image picker on iOS/Android, and\r\n * falls back gracefully to the web camera on non-native platforms.\r\n *\r\n * The returned `dataUrl` is:\r\n * - On native: the result of `Capacitor.convertFileSrc(photo.path)`, which\r\n *   converts the native file path to an HTTP URL the WebView can display.\r\n * - On web/PWA: `photo.webPath` as-is.\r\n *\r\n * This service has no dependency on `WebFileService`; it is a fully independent\r\n * adapter registered by `provideKeepUiCapacitor()`.\r\n */\r\n@Injectable()\r\nexport class CapacitorFileService implements FilePort {\r\n  async pickImage(): Promise<FileResult> {\r\n    const photo = await Camera.getPhoto({\r\n      resultType: CameraResultType.Uri,\r\n      source: CameraSource.Photos,\r\n      quality: 90,\r\n    });\r\n\r\n    // `photo.path` is the native file path (only available on native platforms).\r\n    // `photo.webPath` is always available but may be undefined on some edge cases.\r\n    const rawPath = photo.path ?? photo.webPath ?? '';\r\n\r\n    // On a native Capacitor context, convert the native path to a WebView-friendly URL.\r\n    const dataUrl = Capacitor.isNativePlatform()\r\n      ? Capacitor.convertFileSrc(rawPath)\r\n      : rawPath;\r\n\r\n    return {\r\n      dataUrl,\r\n      mimeType: `image/${photo.format}`,\r\n    };\r\n  }\r\n}\r\n","import { EnvironmentProviders, makeEnvironmentProviders } from '@angular/core';\r\nimport { FILE_PORT } from '@keepui/ui';\r\nimport { CapacitorFileService } from '../services/capacitor-file.service';\r\n\r\n/**\r\n * Registers KeepUI providers for an **Angular + Capacitor** application.\r\n *\r\n * Registers `CapacitorFileService` as the implementation of `FILE_PORT`,\r\n * enabling `ImagePreviewComponent` to use the device's native image picker.\r\n *\r\n * Add to `app.config.ts` **instead of** `provideKeepUi()`:\r\n * ```ts\r\n * import { provideKeepUiCapacitor } from '@keepui/ui/capacitor';\r\n *\r\n * export const appConfig: ApplicationConfig = {\r\n *   providers: [provideKeepUiCapacitor()],\r\n * };\r\n * ```\r\n *\r\n * Prerequisites:\r\n * - `@capacitor/camera` plugin installed and synced (`npx cap sync`)\r\n * - Camera permissions declared in `AndroidManifest.xml` / `Info.plist`\r\n */\r\nexport function provideKeepUiCapacitor(): EnvironmentProviders {\r\n  return makeEnvironmentProviders([\r\n    { provide: FILE_PORT, useClass: CapacitorFileService },\r\n  ]);\r\n}\r\n","// Public API Surface of @keepui/ui/capacitor\r\n\r\nexport * from './lib/services/capacitor-file.service';\r\nexport * from './lib/providers/provide-keep-ui-capacitor';\r\n","/**\n * Generated bundle index. Do not edit.\n */\n\nexport * from './public-api';\n"],"names":[],"mappings":";;;;;;AAMA;;;;;;;;;;;;;AAaG;MAEU,oBAAoB,CAAA;AAC/B,IAAA,MAAM,SAAS,GAAA;AACb,QAAA,MAAM,KAAK,GAAG,MAAM,MAAM,CAAC,QAAQ,CAAC;YAClC,UAAU,EAAE,gBAAgB,CAAC,GAAG;YAChC,MAAM,EAAE,YAAY,CAAC,MAAM;AAC3B,YAAA,OAAO,EAAE,EAAE;AACZ,SAAA,CAAC;;;QAIF,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,IAAI,KAAK,CAAC,OAAO,IAAI,EAAE;;AAGjD,QAAA,MAAM,OAAO,GAAG,SAAS,CAAC,gBAAgB;AACxC,cAAE,SAAS,CAAC,cAAc,CAAC,OAAO;cAChC,OAAO;QAEX,OAAO;YACL,OAAO;AACP,YAAA,QAAQ,EAAE,CAAA,MAAA,EAAS,KAAK,CAAC,MAAM,CAAA,CAAE;SAClC;IACH;+GArBW,oBAAoB,EAAA,IAAA,EAAA,EAAA,EAAA,MAAA,EAAA,EAAA,CAAA,eAAA,CAAA,UAAA,EAAA,CAAA,CAAA;mHAApB,oBAAoB,EAAA,CAAA,CAAA;;4FAApB,oBAAoB,EAAA,UAAA,EAAA,CAAA;kBADhC;;;AChBD;;;;;;;;;;;;;;;;;;AAkBG;SACa,sBAAsB,GAAA;AACpC,IAAA,OAAO,wBAAwB,CAAC;AAC9B,QAAA,EAAE,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,oBAAoB,EAAE;AACvD,KAAA,CAAC;AACJ;;AC3BA;;ACAA;;AAEG;;;;"}