@purplle/sidebar 1.0.0 → 1.0.1

package/CHANGELOG.md

@@ -2,5 +2,5 @@
 
 ## 1.0.0
 
-- Initial enterprise-ready release of `@purplle/sidebar`.
+- Initial enterprise-ready release of `@your-org/prism-sidebar`.
 - Includes framework-agnostic web component, tests, docs, and CI templates.

package/README.md

@@ -1,45 +1,28 @@
-# @purplle/sidebar
+# @avesh.k/prism-sidebar
 
-Framework-agnostic sidebar package powered by native Web Components.
-
-Custom element tag: `prism-sidebar`
+Framework-agnostic Prism sidebar package powered by native Web Components.
 
 ## Install
 
 ```bash
-npm i @purplle/sidebar
+npm i @avesh.k/prism-sidebar
 ```
 
 ## Registration
 
 ```ts
-import { registerPrismSidebar } from '@purplle/sidebar'
+import { registerPrismSidebar } from '@avesh.k/prism-sidebar'
 registerPrismSidebar()
 ```
 
-## Quick Start
-
-```html
-<script type="module">
-  import { registerPrismSidebar } from '@purplle/sidebar'
-  registerPrismSidebar()
-</script>
-<prism-sidebar
-  token="abc"
-  api-base-url="https://example.com/"
-  active-path="/path1"
-  target="_self"
-  aria-label="Main navigation"
-  width="240px"
-></prism-sidebar>
-```
-
 ## Attributes
 
-- `token` (default: `''`)
-- `api-base-url` (default: `''`)
-- `active-path` (default: `''`)
-- `target` (`_self | _blank | _top`, default: `_self`)
+- `token` (required for API calls)
+- `api-url` (preferred menu endpoint)
+- `api-base-url` (legacy alias for `api-url`)
+- `base-url` (default: current origin)
+- `active-path`
+- `target` (`_self | _blank | _top`, default: `_top`)
 - `use-shadow-dom` (default: `true`)
 - `aria-label` (default: `Sidebar navigation`)
 - `collapsed` (default: `true`)
@@ -50,36 +33,157 @@ registerPrismSidebar()
 - `home-url` (default: `/`)
 - `logout-text` (default: `Logout`)
 - `logout-path` (default: `/sentinel/logout`)
-- `error` (default: `''`)
+- `error` (fallback message override)
+
+## JS Properties
+
+- `token`
+- `baseUrl`
+- `apiBaseUrl`
+- `apiUrl`
+- `activePath`
+- `target`
+- `useShadowDom`
+- `ariaLabel`
+- `collapsed`
+- `autoNavigate`
+- `width`
+- `title`
+- `subtitle`
+- `homeUrl`
+- `logoutText`
+- `logoutPath`
+- `error`
+
+## Events
+
+- `sidebar-loaded` (`detail: { menu }`)
+- `sidebar-error` (`detail: { message, cause? }`)
+- `sidebar-item-click` (`detail: { item, resolvedPath, target }`)
+
+## Methods
+
+- `refresh()`
+- `setActivePath(path)`
+- `setConfig(partialConfig)`
+
+## Menu API Shape
+
+The component accepts either of the following API response formats:
+
+```json
+{ "data": { "menu": [/* items */] } }
+```
+
+or
+
+```json
+{ "menu": [/* items */] }
+```
+
+Each item requires:
+
+```json
+{ "id": "string", "name": "string", "path": "/route", "children": [] }
+```
+
+`url` is also accepted as a legacy alias for `path`.
+
+## Plain HTML
+
+```html
+<script type="module">
+  import { registerPrismSidebar } from '@avesh.k/prism-sidebar'
+  registerPrismSidebar()
+</script>
+<prism-sidebar
+  token="abc"
+  base-url="https://example.com"
+  api-url="https://example.com/sentinel/api/v1/menu"
+  active-path="/orders"
+  target="_top"
+  width="240px"
+></prism-sidebar>
+```
+
+## CDN Usage
+
+```html
+<script type="module">
+  import('https://cdn.jsdelivr.net/npm/@avesh.k/prism-sidebar@1.0.5/dist/prism-sidebar.js')
+    .then(({ registerPrismSidebar }) => registerPrismSidebar())
+</script>
+<prism-sidebar token="abc" base-url="https://example.com"></prism-sidebar>
+```
 
 ## React
 
 ```tsx
 import { useEffect } from 'react'
+import { registerPrismSidebar } from '@avesh.k/prism-sidebar'
 
 export function App() {
   useEffect(() => {
-    import('@avesh.k/prism-sidebar').then((mod: any) => {
-        if (mod?.registerPrismSidebar) mod.registerPrismSidebar();
-      }).catch(() => {});
+    registerPrismSidebar()
   }, [])
-  return <prism-sidebar token="abc" api-base-url="https://api.example.com/menu" />
+  return <prism-sidebar token="abc" api-url="https://example.com/sentinel/api/v1/menu" />
 }
 ```
 
+## Angular
+
+Register once in bootstrap and consume directly:
+
+```html
+<prism-sidebar [attr.token]="token" [attr.api-base-url]="apiBaseUrl"></prism-sidebar>
+```
+
 ## SolidJS
 
 ```tsx
 import { onMount } from 'solid-js'
-import { registerPrismSidebar } from '@purplle/sidebar'
+import { registerPrismSidebar } from '@avesh.k/prism-sidebar'
 
 export default function App() {
-  onMount(() => {
-    import('@avesh.k/prism-sidebar').then((mod: any) => {
-        if (mod?.registerPrismSidebar) mod.registerPrismSidebar();
-      }).catch(() => {});
-      })
-  return <prism-sidebar token="abc" api-base-url="https://api.example.com/menu" />
+  onMount(() => registerPrismSidebar())
+  return <prism-sidebar token="abc" api-url="https://example.com/sentinel/api/v1/menu" />
 }
 ```
 
+## iframe-safe activePath
+
+Pass `active-path` from the host application to avoid iframe routing mismatch. This is the recommended integration pattern in nested iframe environments.
+
+## Type Exports
+
+```ts
+import type {
+  SidebarConfig,
+  SidebarConfigInput,
+  SidebarNavigationTarget,
+  SidebarMenuItem,
+  SidebarLoadedEventDetail,
+  SidebarErrorEventDetail,
+  SidebarItemClickEventDetail
+} from '@avesh.k/prism-sidebar'
+```
+
+## Testing
+
+```bash
+npm run test
+npm run test:e2e
+```
+
+## Publishing
+
+Set `.npmrc` for internal registry and publish with:
+
+```bash
+npm run build
+npm publish
+```
+
+## Versioning
+
+Use semantic versioning: patch for fixes, minor for backward-compatible features, major for breaking changes.