@htmlbricks/hb-auth-social-login-button 0.71.35 → 0.71.36

package/README.md

@@ -1,48 +1,152 @@
-## `hb-auth-social-login-button` — auth-social-login-button
+# `hb-auth-social-login-button`
 
-**Category:** auth | **Tags:** auth, oauth
+## Summary
 
-### What it does
+Web component: a square, keyboard-accessible control that starts an OAuth-style redirect for a configured provider (built-in SVGs for GitLab, GitHub, Facebook, Google, and Authentik), or emits a custom event when the provider cannot be started from built-in URL rules. On return to the same page, it can detect tokens or codes in `location.href` and exchange them via `simple-serverless-auth-client` when a server URL and cookie name are set.
 
-Clickable OAuth provider tile (default SVGs for Google, GitHub, GitLab, Facebook, Authentik; overridable via slot). Builds the provider authorization URL from `provider` params or uses a prebuilt `url`, then parses the return URL to exchange code/token with `simple-serverless-auth-client` when `social_auth_server_url` and `auth_cookie_name` are set. Emits `oauthFlowRedirectStart` immediately before redirecting to the provider, then `oauthFlowInit`, `oauthFlowSuccess`, or `oauthFlowCustom` for custom flows.
+## What it does
 
-### Custom element
+- Renders a clickable `#icon-content` region (`role="button"`, `tabindex="0"`) that runs `socialLogin()` on click or Enter/Space.
+- If `provider.url` is set, dispatches `oauthFlowRedirectStart` and sets `location.href` to that URL.
+- Else, if `provider.params` includes `client_id` and `redirect_url`, builds a provider-specific authorize URL (see Logic), dispatches `oauthFlowRedirectStart`, then redirects.
+- Else logs a warning and dispatches `oauthFlowCustom`.
+- On mount, `detectByUri()` inspects `location.href` for provider-specific return patterns; when matched, dispatches `oauthFlowInit` and may call `Authorize.socialLoginOauthAnswer` if both `social_auth_server_url` and `auth_cookie_name` are truthy. On success, either navigates to `redirectonlogin` or dispatches `oauthFlowSuccess` with `{ token }`.
 
-`hb-auth-social-login-button`
+## Appearance
 
-### Attributes / props (snake_case)
+| Aspect | Behavior |
+| --- | --- |
+| Host | `display: block`, fixed size `2.5rem` × `2.5rem`, padding `0.625rem`. |
+| `#icon` | Fills host, transparent background, `position: relative`. |
+| `#icon-content` | Absolutely positioned, vertically centered, `cursor: pointer`, transparent background. |
+| Default artwork | Inline SVGs with `part="provider_icon"` for known `provider.name` values; unknown name shows literal text `btn` inside the default slot fallback. |
+| Focus | `:focus-visible` uses outline and radius from CSS variables (see Styling). |
 
-| Property | Type | Notes |
+## Logic
+
+| Step | Condition | Action |
 | --- | --- | --- |
-| `id` | string (optional) | Element identifier. |
-| `style` | string (optional) | Inline style string. |
-| `social_auth_server_url` | string (optional) | Server URL for token exchange. |
-| `auth_cookie_name` | string (optional) | Cookie name used by the auth client. |
-| `redirectonlogin` | string (optional) | Post-login redirect. |
-| `provider` | object (optional) | JSON: `{ url?: string; name: "facebook" \| "google" \| "gitlab" \| "github" \| "authentik"; params?: { redirect_url; client_id; scope; auth_server_url? } }`. |
+| Parse `provider` | `provider` is a string | `JSON.parse` in an `$effect` (errors logged to console). |
+| Start login | Missing `provider.name`, or both `provider.url` and `provider.params` missing | `console.error`, return. |
+| Prebuilt URL | `provider.url` set | `oauthFlowRedirectStart`, then `location.href = provider.url`. |
+| Composed URL | `provider.params.client_id` and `provider.params.redirect_url` | Build URL by `provider.name`, then `oauthFlowRedirectStart` and redirect. |
+| No URL | Otherwise | `console.warn`, `oauthFlowCustom`. |
+| Google URL | `google` | `https://accounts.google.com/o/oauth2/v2/auth` with `response_type=token`, `scope`, `client_id`, `redirect_uri`, etc. |
+| GitHub URL | `github` | `https://github.com/login/oauth/authorize` with `scope`, `client_id`, `redirect_uri`. |
+| GitLab URL | `gitlab` | `https://gitlab.com/oauth/authorize` with `response_type=code`, `state`, `scope`, `client_id`, `redirect_uri`. |
+| Facebook URL | `facebook` | Same host/path pattern as GitLab in code: `https://gitlab.com/oauth/authorize?...` (same query shape as `gitlab`). |
+| Authentik URL | `authentik` | `` `${provider.params.auth_server_url}/application/o/authorize/?` `` plus `scope`, `response_type=code`, `state`, `client_id`, `redirect_uri`. |
+| Return: Google | `provider.name === "google"`, URL contains `access_token=` and `google` | Extract token after `access_token=`, call server exchange with `{ provider, token }`, dispatch `oauthFlowInit` with `{ provider, token }`. |
+| Return: GitHub | `github`, `code=`, `provider=github` | Code as `token` / `tmpCode`, server exchange, `oauthFlowInit` with `token` and `tmpCode`. |
+| Return: Facebook | `facebook`, `code=`, `provider=facebook` | Derives `redirect_uri` by stripping `state` and `code` segments from `location.href`, server exchange, `oauthFlowInit` includes `redirect_uri`. |
+| Return: GitLab | `gitlab`, `code=`, `provider=gitlab` | Same style of `redirect_uri` derivation and `oauthFlowInit` as other code-based providers. |
+| Return: Authentik | `authentik`, `code=`, `provider=authentik` | Same pattern as GitLab/Facebook for exchange and `oauthFlowInit`. |
+| Server exchange | `auth_cookie_name` and `social_auth_server_url` both truthy | `Authorize.socialLoginOauthAnswer(providerPayload, { authUrl: social_auth_server_url, authCookieName: auth_cookie_name })`. |
+| After exchange | `redirectonlogin` truthy | `location.href = redirectonlogin`. |
+| After exchange | No `redirectonlogin` | `oauthFlowSuccess` with `{ token: resolvedToken }`. |
+
+## Custom element
+
+| Tag |
+| --- |
+| `hb-auth-social-login-button` |
+
+## Attributes
+
+Web component attributes are strings; complex values use JSON strings. Boolean-like project rules elsewhere do not apply to the props used here beyond normal string attributes.
+
+| Attribute | Role in code |
+| --- | --- |
+| `id` | Bound to `id`; default `""` in destructuring. |
+| `provider` | Provider config; coerced from JSON string if passed as string. Must include `name` and either `url` or `params` (see Logic). |
+| `social_auth_server_url` | Passed to `Authorize.socialLoginOauthAnswer` as `authUrl` when set with `auth_cookie_name`. |
+| `auth_cookie_name` | Passed as `authCookieName`; default `"hb_session"` in destructuring. |
+| `redirectonlogin` | If set after successful exchange, full-page redirect to this URL instead of emitting `oauthFlowSuccess`. |
 
-**Slots:** `default` (custom icon or label). **CSS parts:** `provider_icon` on built-in provider SVGs. **i18n:** Italian and English in metadata.
+The TypeScript `Component` type also includes optional `style`, which is not read from `$props()` in `component.wc.svelte` (the `style` binding is commented out).
 
-### Events (`CustomEvent` names)
+## Events
 
-- **`oauthFlowSuccess`** — `{ token: string }`
-- **`oauthFlowRedirectStart`** — `{ provider: IProvider }` (`IProvider` = facebook \| google \| gitlab \| github \| authentik)
-- **`oauthFlowInit`** — `{ token?: string; provider: IProvider; tmpCode?: string; redirect_uri?: string }`
-- **`oauthFlowCustom`** — `{ provider: IProvider }`
+All events are `CustomEvent` dispatched on the host element.
 
-### Usage notes
+| Event | `detail` |
+| --- | --- |
+| `oauthFlowRedirectStart` | `{ provider: IProvider }` |
+| `oauthFlowInit` | `{ token?: string; provider: IProvider; tmpCode?: string; redirect_uri?: string }` |
+| `oauthFlowSuccess` | `{ token: string }` |
+| `oauthFlowCustom` | `{ provider: IProvider }` |
+
+`IProvider` in types: `"facebook" \| "google" \| "gitlab" \| "github" \| "authentik"`.
+
+## Styling (vars / parts / slots)
+
+### CSS custom properties
+
+| Variable | Used in | Fallback in SCSS |
+| --- | --- | --- |
+| `--bulma-link` | `#icon-content:focus-visible` outline color | `#485fc7` |
+| `--bulma-radius` | `#icon-content:focus-visible` border radius | `0.25rem` |
 
-- Bulma theme variables (`--bulma-*`) apply where the host uses Bulma.
-- Provider artwork aligns with common OAuth brands; the default slot can replace the built-in SVGs.
-- Built-in SVGs use a transparent background and export **`::part(provider_icon)`** so the parent page can style the icon (size, `filter`, etc.).
-- Use `i18nlang` on parent `hb-auth` or this component’s i18n metadata where wired.
+### `::part`
 
-### Minimal HTML example
+| Part | Target |
+| --- | --- |
+| `provider_icon` | Default provider `<svg>` elements (`part="provider_icon"`). |
+
+### Slots
+
+| Slot | Description |
+| --- | --- |
+| `default` | Replaces default slot content (built-in SVGs or the `btn` fallback). Use for custom artwork or label inside the control. |
+
+## TypeScript
+
+Authoring types live in `types/webcomponent.type.d.ts`:
+
+```ts
+type IProvider = "facebook" | "google" | "gitlab" | "github" | "authentik";
+
+export type Component = {
+  id?: string;
+  style?: string;
+  social_auth_server_url?: string;
+  auth_cookie_name?: string;
+  redirectonlogin?: string;
+  provider:
+    | {
+        url?: string;
+        name: IProvider;
+        params?: {
+          redirect_url: string;
+          client_id: string;
+          scope: string;
+          auth_server_url?: string;
+        };
+      }
+    | undefined;
+};
+
+export type Events = {
+  oauthFlowSuccess: { token: string };
+  oauthFlowInit: {
+    token?: string;
+    provider: IProvider;
+    tmpCode?: string;
+    redirect_uri?: string;
+  };
+  oauthFlowRedirectStart: { provider: IProvider };
+  oauthFlowCustom: { provider: IProvider };
+};
+```
+
+## Minimal example
 
 ```html
 <hb-auth-social-login-button
-  provider='{"name":"google","url":"https://accounts.google.com/o/oauth2/v2/auth?..."}'
-  social_auth_server_url="https://auth.example.com"
-  auth_cookie_name="session"
+  provider='{"name":"google","url":"https://accounts.google.com/o/oauth2/v2/auth?client_id=YOUR_CLIENT&redirect_uri=YOUR_REDIRECT&response_type=token&scope=openid%20email"}'
+  social_auth_server_url="https://your-auth.example"
+  auth_cookie_name="hb_session"
 ></hb-auth-social-login-button>
 ```
+
+Using composed params instead of `url` requires at least `name`, `params.client_id`, `params.redirect_url`, and `params.scope` so the component can build the authorize URL before redirecting.

package/manifest.json

@@ -183,11 +183,24 @@
     }
   },
   "styleSetup": {
-    "vars": [],
+    "vars": [
+      {
+        "name": "--bulma-link",
+        "valueType": "color",
+        "defaultValue": "#485fc7",
+        "description": "Focus-visible outline on the clickable icon area (`#icon-content`)."
+      },
+      {
+        "name": "--bulma-radius",
+        "valueType": "number",
+        "defaultValue": "0.375rem",
+        "description": "Border radius for the focus ring around the icon control."
+      }
+    ],
     "parts": [
       {
         "name": "provider_icon",
-        "description": "Default built-in provider SVG (GitLab, GitHub, Facebook, Google, Authentik). Exposed so the host can adjust size, filters, or colors (e.g. `hb-auth-social-login-button::part(provider_icon) { ... }`)."
+        "description": "Built-in provider SVG (Google, GitHub, GitLab, Facebook, Authentik). Style size, `filter`, or color from the light DOM (e.g. `hb-auth-social-login-button::part(provider_icon)`)."
       }
     ]
   },
@@ -195,7 +208,7 @@
   "htmlSlots": [
     {
       "name": "default",
-      "description": "Custom provider icon or label inside the login control."
+      "description": "Replace the default provider artwork or add a custom label inside the square control; used when you do not rely on the built-in SVG set."
     }
   ],
   "i18n": [
@@ -265,5 +278,5 @@
   },
   "iifePath": "main.iife.js",
   "repoName": "@htmlbricks/hb-auth-social-login-button",
-  "version": "0.71.35"
+  "version": "0.71.36"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@htmlbricks/hb-auth-social-login-button",
-  "version": "0.71.35",
+  "version": "0.71.36",
   "contributors": [],
   "description": "Clickable OAuth provider tile (default SVGs for Google, GitHub, GitLab, Facebook, Authentik; overridable via slot). Builds the provider authorization URL from `provider` params or redirects to a prebuilt `url`, then on return parses the current page URL to exchange the code/token with `simple-serverless-auth-client` when `social_auth_server_url` and `auth_cookie_name` are set. Emits `oauthFlowRedirectStart` immediately before leaving for the provider, then `oauthFlowInit`, `oauthFlowSuccess`, or `oauthFlowCustom` as the flow progresses.",
   "licenses": [