@igamingcareer/igaming-components 1.0.85 → 1.0.87

package/Readme.md

@@ -123,7 +123,130 @@ export function FollowCompaniesExample({ company }: { company: Company }) {
 }
 ```
 
-Use `followDisabled` to block interactions for unauthenticated users, and `isFollowing` to keep the UI in sync with your data source.
+## Company admin shell layout
+
+The CompanyAdminShell component now renders the admin tabs internally. It handles tab routing, renders the built-in admin views, and surfaces update events so the parent can persist changes.
+
+### Permission system
+
+Permissions decide whether a tab is visible and whether fields render as editable inputs or read-only text. Use a boolean per section:
+
+```ts
+export type CompanyAdminPermissions = {
+  canViewOverview?: boolean;
+  canManageProducts?: boolean;
+  canManagePeople?: boolean;
+  canManageJobs?: boolean;
+  canManageEvents?: boolean;
+  canManageNews?: boolean;
+  canManageSettings?: boolean;
+};
+```
+
+### Update events
+
+Each admin section emits update events so the parent can save to the backend and update local state.
+
+```ts
+import type { CompanyAdminUpdateEvent } from "@igamingcareer/igaming-components";
+
+const handleUpdate = async (event: CompanyAdminUpdateEvent) => {
+  console.log("update event", event);
+  // call backend API
+  // update local state based on event.type
+};
+```
+
+### Example usage
+
+```tsx
+import { useState } from "react";
+import {
+  CompanyAdminShell,
+  type AdminTab,
+  type CompanyAdminPermissions,
+  type CompanyAdminUpdateEvent,
+} from "@igamingcareer/igaming-components";
+
+export function CompanyAdminExample({ company }: { company: Company }) {
+  const [activeTab, setActiveTab] = useState<AdminTab>("overview");
+  const [isSaving, setIsSaving] = useState(false);
+
+  const permissions: CompanyAdminPermissions = {
+    canViewOverview: true,
+    canManageProducts: true,
+    canManagePeople: false,
+    canManageJobs: true,
+    canManageEvents: true,
+    canManageNews: false,
+    canManageSettings: true,
+  };
+
+  const handleUpdate = async (event: CompanyAdminUpdateEvent) => {
+    setIsSaving(true);
+    try {
+      // call backend API
+      console.log("update", event);
+    } finally {
+      setIsSaving(false);
+    }
+  };
+
+  return (
+    <CompanyAdminShell
+      company={company}
+      role="admin"
+      permissions={permissions}
+      activeTab={activeTab}
+      onTabChange={setActiveTab}
+      onUpdate={handleUpdate}
+      isSaving={isSaving}
+    />
+  );
+}
+```
+
+### CompanyAdminShell props
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `company` | `Company` | Full company object used for header and admin sections. |
+| `companyName` | `string` | Optional override for the display name shown in the header. |
+| `companySlug` | `string` | Optional override for the slug used in the header. |
+| `activeTab` | `AdminTab` | Current active tab key (controlled). |
+| `visibleTabs` | `AdminTab[]` | Tabs that should appear in the admin UI (optional override). |
+| `onTabChange` | `(tab: AdminTab) => void` | Called when a user switches tabs. |
+| `role` | `CompanyAdminRole` | Role label shown in the header (defaults to `admin`). |
+| `permissions` | `CompanyAdminPermissions` | Permission map for tabs and editability. |
+| `companyMeta` | `CompanyAdminCompanyMeta` | Optional metadata for the header summary. |
+| `summaryStats` | `CompanyAdminSummaryStat[]` | Optional summary stats for the header (derived from `company` when omitted). |
+| `onUpdate` | `(event: CompanyAdminUpdateEvent) => void \| Promise<void>` | Optional update callback for child sections. |
+| `isSaving` | `boolean` | Optional saving state for buttons. |
+
+### Backend integration guide
+
+1. Listen for `CompanyAdminUpdateEvent` from the active admin tab.
+2. Call your backend endpoint for that section.
+3. Merge the returned data into your local `company` state.
+4. Provide the updated `company` back to the admin components.
+
+### Component patterns
+
+- Each admin section owns local `formState` and emits a full payload via `onUpdate`.
+- When `canEdit` is `false`, fields render as read-only text and edit controls are hidden.
+- Use `isSaving` to lock save buttons and show spinners.
+
+### Best practices
+
+- Use `onUpdate` to connect each tab to your backend and keep `company` state in sync.
+- Use separate state slices for admin-only data (e.g., settings) if it is not part of the core company API.
+- Guard any optional permissions with defaults so read-only views remain safe.
+
+### Troubleshooting
+
+- **Nothing renders:** ensure the active tab is included in `visibleTabs` and has permission enabled.
+- **Save button disabled:** verify `isSaving` is `false` and `canEdit` is `true`.
+- **Updates not persisting:** confirm your parent handler merges the payload back into company state.
 
 ## Save company callbacks (CompanyCard + CompanyDetail)
 
@@ -222,6 +345,29 @@ export function CompanyDetailWithClaim({ company }: { company: Company }) {
 }
 ```
 
+## Claim company CTA (CompanyClaim)
+
+Use the `CompanyClaim` component to render a minimal “Claim this company” CTA. It is fully controlled by props and emits a click event upward without any auth or API logic.
+
+```tsx
+import { CompanyClaim } from "@igamingcareer/igaming-components";
+
+export function CompanyClaimExample({ company, canClaim }: { company: Company; canClaim: boolean }) {
+  const handleClaimClick = () => {
+    // optional: analytics or open your claim flow
+    console.log("claim company", { companyId: company.id });
+  };
+
+  return (
+    <CompanyClaim
+      isClaimed={company.claimedStatus === "claimed"}
+      canClaim={canClaim}
+      onClaimClick={handleClaimClick}
+    />
+  );
+}
+```
+
 ## CV upload from the dashboard
 
 The dashboard emits CV upload events so the host application can upload, store,