pict-section-login 0.0.1 → 1.0.0

package/README.md

@@ -0,0 +1,140 @@
+# Pict Section Login
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+A drop-in login section for Pict applications. Renders a styled login form, calls out to [orator-authentication](https://github.com/stevenvelozo/orator-authentication) (or any custom backend) for sign-in / sign-out / session-check, stores the resulting session on the Pict AppData tree, and exposes override hooks so you can chain navigation, route resolution, or any other post-auth behavior.
+
+## Features
+
+- **Drop-In View** -- Extends `pict-view`; register with `pict.addView(...)` and call `render()` to get a complete login form
+- **Orator-Authentication Ready** -- Default endpoints match the standard `orator-authentication` routes; works out of the box
+- **Custom Backend Friendly** -- Every endpoint is configurable, both POST (JSON body) and GET (URL-encoded credentials) are supported
+- **Session Management** -- `login`, `logout`, and `checkSession` methods plus automatic check-on-load
+- **OAuth Provider Support** -- Optional OAuth button row populated from `/OAuth/Providers` and redirected through `/OAuth/Begin`
+- **AppData Integration** -- Session data is written to a configurable Pict manifest address (default `AppData.Session`)
+- **Override Hooks** -- `onLoginSuccess`, `onLoginFailed`, `onLogout`, `onSessionChecked` for post-auth navigation and app state updates
+- **Router Friendly** -- Designed to cooperate with [pict-router](https://github.com/stevenvelozo/pict-router) for route-guarded navigation and post-login redirects
+- **Styled Out of the Box** -- Embedded CSS design system renders a polished card with no extra styling required
+
+## Installation
+
+```bash
+npm install pict-section-login
+```
+
+## Quick Start
+
+```javascript
+const libPict = require('pict');
+const libPictSectionLogin = require('pict-section-login');
+
+class MyLoginView extends libPictSectionLogin
+{
+	onLoginSuccess(pSessionData)
+	{
+		this.log.info('Logged in as', pSessionData?.UserRecord?.LoginID);
+		// e.g. this.pict.PictApplication.showProtectedApp();
+	}
+}
+
+const _Pict = new libPict();
+_Pict.addView(
+	'MyLogin',
+	{
+		"ViewIdentifier": "MyLogin",
+		"TargetElementAddress": "#Pict-Login-Container"
+	},
+	MyLoginView);
+
+_Pict.views.MyLogin.render();
+```
+
+Drop a mount point into your page:
+
+```html
+<div id="Pict-Login-Container"></div>
+```
+
+That's the whole thing for a default orator-authentication wiring. See [docs/quickstart.md](docs/quickstart.md) for custom backends, OAuth, hooks, and AppData access.
+
+## Configuration Overview
+
+| Key | Default | Purpose |
+|---|---|---|
+| `LoginEndpoint` | `/1.0/Authenticate` | Endpoint to POST credentials to |
+| `LoginMethod` | `POST` | `POST` (JSON body) or `GET` (URL-encoded) |
+| `LogoutEndpoint` | `/1.0/Deauthenticate` | Endpoint to end the session |
+| `CheckSessionEndpoint` | `/1.0/CheckSession` | Endpoint to validate an existing session |
+| `OAuthProvidersEndpoint` | `/1.0/OAuth/Providers` | List of available OAuth providers |
+| `OAuthBeginEndpoint` | `/1.0/OAuth/Begin` | OAuth redirect prefix |
+| `CheckSessionOnLoad` | `true` | Auto-call `checkSession` on first render |
+| `ShowOAuthProviders` | `false` | Render OAuth buttons alongside the form |
+| `SessionDataAddress` | `AppData.Session` | Manifest address to store session data |
+| `TargetElementAddress` | `#Pict-Login-Container` | CSS selector for the mount point |
+
+See [docs/configuration.md](docs/configuration.md) for the full reference.
+
+## Public API
+
+| Method | Purpose |
+|---|---|
+| `login(pUsername, pPassword, fCallback)` | Authenticate with credentials |
+| `logout(fCallback)` | End the current session |
+| `checkSession(fCallback)` | Validate an existing session (e.g. from a cookie) |
+| `loadOAuthProviders(fCallback)` | Fetch and render OAuth provider buttons |
+| `onLoginSuccess(pSessionData)` | Override hook fired after successful login |
+| `onLoginFailed(pError)` | Override hook fired after failed login |
+| `onLogout()` | Override hook fired after logout |
+| `onSessionChecked(pSessionData)` | Override hook fired after a session check |
+
+See [docs/api-reference.md](docs/api-reference.md) and [docs/code-snippets.md](docs/code-snippets.md) for complete details and runnable examples.
+
+## Router Integration
+
+`pict-section-login` pairs naturally with [pict-router](https://github.com/stevenvelozo/pict-router): register your routes with `SkipRouteResolveOnAdd: true`, call `checkSession()` before resolving, and implement a `PendingRoute` redirect in `onLoginSuccess`. See [docs/router-integration.md](docs/router-integration.md) for the full pattern, including route guards and post-login redirects.
+
+## Documentation
+
+- [Overview](docs/README.md)
+- [Quick Start](docs/quickstart.md)
+- [Architecture](docs/architecture.md)
+- [Configuration](docs/configuration.md)
+- [API Reference](docs/api-reference.md)
+- [Code Snippets](docs/code-snippets.md)
+- [Embedding Guide](docs/embedding-guide.md)
+- [Router Integration](docs/router-integration.md)
+- [Templates & Styling](docs/templates-and-styling.md)
+
+## Example Applications
+
+- [`example_applications/orator_login`](example_applications/orator_login) -- minimal orator-authentication wiring
+- [`example_applications/custom_login`](example_applications/custom_login) -- custom endpoints + override hooks
+- [`example_applications/oauth_login`](example_applications/oauth_login) -- OAuth provider list integration
+- [`example_applications/harness_app`](example_applications/harness_app) -- full integration: login + pict-router + protected views + top bar
+
+## Testing
+
+```bash
+npm test
+npm run test-browser    # Puppeteer headless browser tests
+npm run coverage
+```
+
+## Related Packages
+
+- [pict](https://github.com/stevenvelozo/pict) -- MVC application framework
+- [pict-view](https://github.com/stevenvelozo/pict-view) -- View base class
+- [pict-router](https://github.com/stevenvelozo/pict-router) -- Hash-based router that pairs with this module
+- [pict-application](https://github.com/stevenvelozo/pict-application) -- Application host and lifecycle
+- [orator-authentication](https://github.com/stevenvelozo/orator-authentication) -- Default backend
+- [fable](https://github.com/stevenvelozo/fable) -- Core service ecosystem
+
+## License
+
+MIT
+
+## Contributing
+
+Pull requests welcome. See the [Retold Contributing Guide](https://github.com/stevenvelozo/retold/blob/main/docs/contributing.md) for the code of conduct, contribution process, and testing requirements.

package/docs/README.md

@@ -0,0 +1,52 @@
+# Pict Section Login
+
+> A drop-in login section for Pict applications
+
+Pict Section Login is a `pict-view` subclass that renders a styled authentication form, talks to a REST backend (the default endpoints match [orator-authentication](https://github.com/stevenvelozo/orator-authentication), but everything is configurable), stores the resulting session on the Pict AppData tree, and exposes override hooks so you can chain navigation, route resolution, or any other post-auth behavior.
+
+The view ships with:
+
+- A container template with a styled card, an error strip, a form area, an OAuth area, and a status area
+- A login form template (username + password + submit)
+- A logged-in status bar with user name, user id, and logout button
+- An OAuth providers row that fetches and renders provider buttons
+- An error template for inline error display
+- An embedded CSS design system covering all of the above
+
+Everything is replaceable via the `Templates` array in the configuration, and the entire visual layer can be restyled by overriding the `CSS` block or simply applying your own rules on top of the `.pict-login-*` classes.
+
+## Features
+
+- **Drop-In View** -- Extends `pict-view`; register via `pict.addView(...)` and call `render()`
+- **Orator-Authentication Ready** -- Default endpoints match the standard orator-authentication routes
+- **Custom Backend Friendly** -- `LoginEndpoint`, `LogoutEndpoint`, `CheckSessionEndpoint`, and OAuth endpoints are all configurable; POST (JSON body) and GET (URL-encoded) are both supported for login
+- **Session Management** -- `login`, `logout`, and `checkSession` methods plus automatic check-on-load via `CheckSessionOnLoad`
+- **OAuth Provider Support** -- `loadOAuthProviders()` fetches the provider list and renders buttons that redirect through `OAuthBeginEndpoint`
+- **AppData Integration** -- Session data is written to a configurable Pict manifest address (default `AppData.Session`) so any template solver or view can read it
+- **Override Hooks** -- `onLoginSuccess`, `onLoginFailed`, `onLogout`, `onSessionChecked` hooks let you chain navigation or app-level state changes
+- **Router Friendly** -- Designed to cooperate with [pict-router](https://github.com/stevenvelozo/pict-router) for route-guarded navigation and post-login redirects
+- **Styled Out of the Box** -- Embedded CSS design system renders a polished card with no extra styling required
+- **No Token Handling** -- Assumes the backend uses secure HTTP-only cookies; the view never touches `localStorage` or `sessionStorage`
+
+## When to Use It
+
+Reach for this view when your Pict application needs to:
+
+- Show a login screen before any protected content is rendered
+- Integrate with `orator-authentication` or any REST auth backend that exposes `authenticate` / `deauthenticate` / `checksession` semantics
+- Display OAuth provider buttons alongside a traditional username/password form
+- Protect routes via `pict-router` and redirect users to their intended page after signing in
+- Provide a consistent session-aware status bar across an application shell
+
+Skip it if your application needs a custom-designed login screen that does not resemble the built-in card layout -- you can still use the `login` / `logout` / `checkSession` methods directly from any view, but the rendering layer assumes the bundled templates.
+
+## Learn More
+
+- [Quick Start](quickstart.md) -- Install, register, and render your first login form
+- [Embedding Guide](embedding-guide.md) -- How to place the login inside an existing Pict application, including shell layouts and auth-gated rendering
+- [Router Integration](router-integration.md) -- Full pattern for `pict-router` route guards, pending-route redirects, and post-login navigation
+- [Templates & Styling](templates-and-styling.md) -- Override the container, form, status, OAuth, and error templates; customize the CSS design system
+- [Architecture](architecture.md) -- Class hierarchy, state diagram, and request flow
+- [Configuration](configuration.md) -- Every key in `default_configuration` with defaults and descriptions
+- [API Reference](api-reference.md) -- Every public method, parameter, callback signature, and override hook
+- [Code Snippets](code-snippets.md) -- A runnable snippet for each exposed function

package/docs/_brand.json

@@ -0,0 +1,18 @@
+{
+	"Hash": "pict-section-login",
+	"Name": "Pict Section Login",
+	"Tagline": "Pict login section for authentication UIs — works with orator-authentication or any custom backend",
+	"Palette": "mix",
+	"Icon": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 96 96\" width=\"96\" height=\"96\">\n\t\t<defs>\n\t\t\t<clipPath id=\"frame-pict-section-login-filled-light\">\n\t\t\t\t<path d=\"M 2 48\n\t\t\tC 2 18.0222416, 18.0222416 2, 48 2\n\t\t\tC 77.9777584 2, 94 18.0222416, 94 48\n\t\t\tC 94 77.9777584, 77.9777584 94, 48 94\n\t\t\tC 18.0222416 94, 2 77.9777584, 2 48 Z\"/>\n\t\t\t</clipPath>\n\t\t</defs>\n\t\t<path d=\"M 2 48\n\t\t\tC 2 18.0222416, 18.0222416 2, 48 2\n\t\t\tC 77.9777584 2, 94 18.0222416, 94 48\n\t\t\tC 94 77.9777584, 77.9777584 94, 48 94\n\t\t\tC 18.0222416 94, 2 77.9777584, 2 48 Z\" fill=\"#34b3ce\"/>\n\t\t<g clip-path=\"url(#frame-pict-section-login-filled-light)\"><circle cx=\"39\" cy=\"48\" r=\"30\" fill=\"#dd6f55\" opacity=\"0.85\"/>\n\t\t\t\t\t<circle cx=\"57\" cy=\"48\" r=\"30\" fill=\"rgba(255,255,255,0.32)\" opacity=\"0.95\"/></g>\n\t\t<text x=\"48\" y=\"50\" text-anchor=\"middle\" dominant-baseline=\"central\"\n\t\t\tfont-family=\"-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif\"\n\t\t\tfont-size=\"28\" font-weight=\"600\"\n\t\t\tfill=\"#ffffff\" letter-spacing=\"-1\">PSL</text>\n\t</svg>",
+	"IconType": "svg",
+	"Favicon": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 96 96\" width=\"96\" height=\"96\">\n\t\t<defs>\n\t\t\t<clipPath id=\"fav-pict-section-login-light\">\n\t\t\t\t<path d=\"M 2 48\n\t\t\tC 2 18.0222416, 18.0222416 2, 48 2\n\t\t\tC 77.9777584 2, 94 18.0222416, 94 48\n\t\t\tC 94 77.9777584, 77.9777584 94, 48 94\n\t\t\tC 18.0222416 94, 2 77.9777584, 2 48 Z\"/>\n\t\t\t</clipPath>\n\t\t</defs>\n\t\t<path d=\"M 2 48\n\t\t\tC 2 18.0222416, 18.0222416 2, 48 2\n\t\t\tC 77.9777584 2, 94 18.0222416, 94 48\n\t\t\tC 94 77.9777584, 77.9777584 94, 48 94\n\t\t\tC 18.0222416 94, 2 77.9777584, 2 48 Z\" fill=\"#34b3ce\"/>\n\t\t<g clip-path=\"url(#fav-pict-section-login-light)\"><circle cx=\"39\" cy=\"48\" r=\"34\" fill=\"#dd6f55\"/>\n\t\t\t\t\t<circle cx=\"57\" cy=\"48\" r=\"34\" fill=\"rgba(255,255,255,0.22)\"/></g>\n\t\t<text x=\"48\" y=\"50\" text-anchor=\"middle\" dominant-baseline=\"central\"\n\t\t\tfont-family=\"-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif\"\n\t\t\tfont-size=\"60\" font-weight=\"800\"\n\t\t\tfill=\"#ffffff\" letter-spacing=\"-1\">P</text>\n\t</svg>",
+	"FaviconDark": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 96 96\" width=\"96\" height=\"96\">\n\t\t<defs>\n\t\t\t<clipPath id=\"fav-pict-section-login-dark\">\n\t\t\t\t<path d=\"M 2 48\n\t\t\tC 2 18.0222416, 18.0222416 2, 48 2\n\t\t\tC 77.9777584 2, 94 18.0222416, 94 48\n\t\t\tC 94 77.9777584, 77.9777584 94, 48 94\n\t\t\tC 18.0222416 94, 2 77.9777584, 2 48 Z\"/>\n\t\t\t</clipPath>\n\t\t</defs>\n\t\t<path d=\"M 2 48\n\t\t\tC 2 18.0222416, 18.0222416 2, 48 2\n\t\t\tC 77.9777584 2, 94 18.0222416, 94 48\n\t\t\tC 94 77.9777584, 77.9777584 94, 48 94\n\t\t\tC 18.0222416 94, 2 77.9777584, 2 48 Z\" fill=\"#83ccdb\"/>\n\t\t<g clip-path=\"url(#fav-pict-section-login-dark)\"><circle cx=\"39\" cy=\"48\" r=\"34\" fill=\"#e9b2a5\"/>\n\t\t\t\t\t<circle cx=\"57\" cy=\"48\" r=\"34\" fill=\"rgba(255,255,255,0.22)\"/></g>\n\t\t<text x=\"48\" y=\"50\" text-anchor=\"middle\" dominant-baseline=\"central\"\n\t\t\tfont-family=\"-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif\"\n\t\t\tfont-size=\"60\" font-weight=\"800\"\n\t\t\tfill=\"#101418\" letter-spacing=\"-1\">P</text>\n\t</svg>",
+	"Colors": {
+		"Primary": "#34b3ce",
+		"Secondary": "#dd6f55",
+		"PrimaryLight": "#34b3ce",
+		"PrimaryDark": "#83ccdb",
+		"SecondaryLight": "#dd6f55",
+		"SecondaryDark": "#e9b2a5"
+	}
+}

package/docs/_cover.md

@@ -0,0 +1,19 @@
+# Pict Section Login
+
+> A drop-in login section for Pict applications
+
+Register it as a Pict view, point it at your auth endpoints, and you get a styled login form, session check, logout, and OAuth button support in a single view class. Override four lifecycle hooks to wire it to your application state, and pair it with pict-router for route-guarded navigation.
+
+- **Drop-In View** -- One `pict.addView(...)` call gives you a complete login form
+- **Orator-Authentication Ready** -- Default endpoints match the standard routes
+- **Custom Backend Friendly** -- Every endpoint is configurable; POST and GET both supported
+- **Session Management** -- `login`, `logout`, and `checkSession` with AppData integration
+- **OAuth Providers** -- Optional OAuth row populated from a providers endpoint
+- **Override Hooks** -- Four clean hooks for post-auth navigation and state updates
+- **Router Friendly** -- Designed to cooperate with pict-router for route guards and post-login redirects
+
+[Overview](README.md)
+[Quick Start](quickstart.md)
+[Embedding Guide](embedding-guide.md)
+[Router Integration](router-integration.md)
+[GitHub](https://github.com/stevenvelozo/pict-section-login)

package/docs/_sidebar.md

@@ -0,0 +1,26 @@
+- Getting Started
+
+  - [Overview](README.md)
+  - [Quick Start](quickstart.md)
+
+- Guides
+
+  - [Embedding Guide](embedding-guide.md)
+  - [Router Integration](router-integration.md)
+  - [Templates & Styling](templates-and-styling.md)
+
+- Reference
+
+  - [Architecture](architecture.md)
+  - [Configuration](configuration.md)
+  - [API Reference](api-reference.md)
+  - [Code Snippets](code-snippets.md)
+
+- Retold Ecosystem
+
+  - [Pict](/pict/pict/)
+  - [Pict View](/pict/pict-view/)
+  - [Pict Router](/pict/pict-router/)
+  - [Pict Application](/pict/pict-application/)
+  - [Orator Authentication](/orator/orator-authentication/)
+  - [Fable](/fable/fable/)

package/docs/_topbar.md

@@ -0,0 +1,10 @@
+# Pict Section Login
+
+- [Overview](README.md)
+- [Quick Start](quickstart.md)
+- [Embedding](embedding-guide.md)
+- [Router Integration](router-integration.md)
+- [Architecture](architecture.md)
+- [API Reference](api-reference.md)
+- [Code Snippets](code-snippets.md)
+- [GitHub](https://github.com/stevenvelozo/pict-section-login)

package/docs/_version.json

@@ -0,0 +1,7 @@
+{
+	"Name": "pict-section-login",
+	"Version": "0.0.1",
+	"Description": "Pict login section for authentication UIs — works with orator-authentication or any custom backend",
+	"GeneratedAt": "2026-04-10T17:25:37.018Z",
+	"GitCommit": "e785649"
+}

package/docs/api-reference.md

@@ -0,0 +1,239 @@
+# API Reference
+
+Every developer-facing method, property, and override hook on `PictSectionLogin`. Signatures follow the source in `source/Pict-Section-Login.js`.
+
+`PictSectionLogin` extends [`pict-view`](https://github.com/stevenvelozo/pict-view), so it inherits all of the standard view lifecycle methods (`render`, `solve`, `initialize`, `onBeforeInitialize`, `onAfterRender`, `onAfterInitialRender`) in addition to the login-specific surface below.
+
+## Public State
+
+Instance properties that the view maintains and that your code is welcome to read (but should generally not write directly):
+
+### `this.authenticated`
+
+- **Type:** `boolean`
+- **Default:** `false`
+- `true` after a successful `login()` or a successful `checkSession()` that returned `LoggedIn: true`.
+- Reset to `false` by `logout()`.
+
+### `this.sessionData`
+
+- **Type:** `object | null`
+- **Default:** `null`
+- The most recent session object returned from the backend. Mirrored to `options.SessionDataAddress` via `fable.manifest.setValueByHash`.
+- Cleared by `logout()`.
+
+### `this.oauthProviders`
+
+- **Type:** `array`
+- **Default:** `[]`
+- Populated by `loadOAuthProviders()`. Each element is whatever the backend returned; `Name` is required, `BeginURL` is optional.
+
+### `this.initialRenderComplete`
+
+- **Type:** `boolean`
+- **Default:** `false`
+- Internal flag; `true` after `onAfterInitialRender()` has run for the first time. Used to guard against duplicate CSS injection and duplicate session checks.
+
+## Authentication Methods
+
+### `login(pUsername, pPassword, fCallback)`
+
+Authenticates against `options.LoginEndpoint`.
+
+| Param | Type | Description |
+|---|---|---|
+| `pUsername` | `string` | The user-supplied username. |
+| `pPassword` | `string` | The user-supplied password. |
+| `fCallback` | `function(pError, pSessionData)` | Optional. Called with an error string on failure or the session object on success. |
+
+Behavior:
+
+1. When `options.LoginMethod === 'POST'` (the default), sends `POST options.LoginEndpoint` with body `{ UserName, Password }` and `Content-Type: application/json`.
+2. When `options.LoginMethod === 'GET'`, sends `GET options.LoginEndpoint/:encodedUsername/:encodedPassword`.
+3. On success (response has `LoggedIn === true`):
+	- Sets `this.authenticated = true`.
+	- Assigns the response to `this.sessionData`.
+	- Calls `fable.manifest.setValueByHash(..., options.SessionDataAddress, sessionData)`.
+	- Renders the status bar (replaces the form).
+	- Calls `this.onLoginSuccess(sessionData)`.
+	- Calls `this.pict.PictApplication.solve()` when that method is available.
+	- Invokes `fCallback(null, sessionData)`.
+4. On failure:
+	- Renders the error template with the response's message.
+	- Calls `this.onLoginFailed(errorMessage)`.
+	- Invokes `fCallback(errorMessage)`.
+
+Called automatically when the user submits the login form; you rarely need to call it directly unless you are driving the view programmatically (tests, SSO handoff, etc.).
+
+### `logout(fCallback)`
+
+Ends the current session.
+
+| Param | Type | Description |
+|---|---|---|
+| `fCallback` | `function(pError)` | Optional. Called when the logout flow finishes. |
+
+Behavior:
+
+1. Sends `GET options.LogoutEndpoint`.
+2. Regardless of the network outcome, clears local state:
+	- `this.authenticated = false`
+	- `this.sessionData = null`
+	- `fable.manifest.setValueByHash(..., options.SessionDataAddress, null)`
+3. Re-renders the login form (replaces the status bar).
+4. Calls `this.onLogout()`.
+5. Calls `this.pict.PictApplication.solve()` when that method is available.
+6. Invokes `fCallback(null)` or `fCallback(errorString)`.
+
+Wired up automatically to the logout button in the status bar template. Call it manually from an application-level logout action if your application has its own logout affordance (e.g. a menu item).
+
+### `checkSession(fCallback)`
+
+Validates the current session against `options.CheckSessionEndpoint`.
+
+| Param | Type | Description |
+|---|---|---|
+| `fCallback` | `function(pError, pSessionData)` | Optional. Called with an error string on network failure or the session object (which may have `LoggedIn: false`) on success. |
+
+Behavior:
+
+1. Sends `GET options.CheckSessionEndpoint`.
+2. If the response has `LoggedIn === true`:
+	- Sets `this.authenticated = true`.
+	- Assigns the response to `this.sessionData`.
+	- Writes the session to `options.SessionDataAddress`.
+	- Renders the status bar.
+3. If `LoggedIn` is not true, leaves the login form visible.
+4. Calls `this.onSessionChecked(sessionData)` (or `this.onSessionChecked(null)` on network failure).
+5. Invokes `fCallback(pError, sessionData)`.
+
+Called automatically after the first render when `options.CheckSessionOnLoad === true` (the default). Call it manually when you want the host application to control the timing (e.g. `CheckSessionOnLoad: false` plus a call from `PictApplication.onAfterInitializeAsync`).
+
+### `loadOAuthProviders(fCallback)`
+
+Fetches the OAuth provider list from `options.OAuthProvidersEndpoint`.
+
+| Param | Type | Description |
+|---|---|---|
+| `fCallback` | `function(pError, pProviders)` | Optional. Called with an array of providers on success. |
+
+Behavior:
+
+1. Sends `GET options.OAuthProvidersEndpoint`.
+2. Stores the returned `Providers` array in `this.oauthProviders`.
+3. Renders the OAuth button row into `#pict-login-oauth-area`.
+4. Each button's click navigates the browser to `<OAuthBeginEndpoint>/<providerName>` (or to `provider.BeginURL` if the provider object supplies one).
+5. Invokes `fCallback(pError, providers)`.
+
+Called automatically after the first render when `options.ShowOAuthProviders === true`.
+
+## Override Hooks
+
+These methods are no-ops by default. Subclass `PictSectionLogin` and override them to hook application logic into the auth flow. The framework calls them at the right time -- you never call them directly.
+
+### `onLoginSuccess(pSessionData)`
+
+Called after a successful `login()`.
+
+| Param | Type | Description |
+|---|---|---|
+| `pSessionData` | `object` | The session object returned from the backend. Always has `LoggedIn: true`. |
+
+Typical use:
+
+- Show the application shell (e.g. `this.pict.PictApplication.showProtectedApp()`).
+- Redirect to a stored pending route (`this.pict.providers.PictRouter.navigate(this.pict.AppData.PendingRoute || '/Dashboard')`).
+- Fire analytics.
+- Load additional user data.
+
+### `onLoginFailed(pError)`
+
+Called after a failed `login()`.
+
+| Param | Type | Description |
+|---|---|---|
+| `pError` | `string` | Human-readable error message from the backend or the network layer. |
+
+Typical use:
+
+- Fire analytics on failed attempts.
+- Show a custom error modal instead of the inline error template.
+- Track rate limiting / lockout state.
+
+### `onLogout()`
+
+Called after a successful `logout()`.
+
+No parameters.
+
+Typical use:
+
+- Show the login view and hide the protected shell (`this.pict.PictApplication.showLogin()`).
+- Clear application-level caches or in-memory state.
+- Navigate to a public landing page.
+
+### `onSessionChecked(pSessionData)`
+
+Called after `checkSession()` completes.
+
+| Param | Type | Description |
+|---|---|---|
+| `pSessionData` | `object \| null` | The session object on success (may be `{ LoggedIn: false }`), or `null` on network failure. |
+
+Typical use:
+
+- Detect a restored session on app load and show the protected shell without requiring the user to re-enter credentials.
+- Detect an expired session and show the login view with an appropriate message.
+- Drive a "restoring session" splash screen off of the timing of this callback.
+
+## Lifecycle Hooks (Inherited from pict-view)
+
+`PictSectionLogin` overrides three standard lifecycle hooks. If you override them in a subclass, call `super.<method>(...)` first so the base behavior still runs.
+
+### `onBeforeInitialize()`
+
+Called before the view is initialized. Used internally to reset state before the first render. Override to run subclass-level setup that must happen before templates are registered.
+
+### `onAfterRender(pRenderable)`
+
+Called after each render pass. Used internally to:
+
+1. Inject CSS via `this.pict.CSSMap.injectCSS()` (first render only).
+2. Render the login form or status bar into the wrapper based on `this.authenticated`.
+3. Wire up the submit handler and logout button.
+
+Override carefully -- call `super.onAfterRender(pRenderable)` first and then add subclass-level DOM work.
+
+### `onAfterInitialRender()`
+
+Called once after the first render. Used internally to:
+
+1. Run `checkSession()` when `CheckSessionOnLoad === true`.
+2. Run `loadOAuthProviders()` when `ShowOAuthProviders === true`.
+3. Set `this.initialRenderComplete = true`.
+
+Override if you want to run one-time subclass setup that depends on the DOM being ready.
+
+## Static Exports
+
+### `PictSectionLogin.default_configuration`
+
+The default configuration object (see [Configuration](configuration.md) for every key). Exported so you can merge it with your own options:
+
+```javascript
+const libPictSectionLogin = require('pict-section-login');
+const tmpDefaults = libPictSectionLogin.default_configuration;
+
+const tmpOptions = Object.assign({}, tmpDefaults, {
+	"LoginEndpoint": "/api/auth/login"
+});
+```
+
+## Error Handling Contract
+
+The view does its best to keep the UI consistent with server state:
+
+- Network failures are surfaced as strings through the error hook and the inline error template.
+- `logout()` always clears local state, even if the server is unreachable. The user should never be stuck in an "I can't log out" loop.
+- `checkSession()` treats a network failure as "session unknown" -- it calls `onSessionChecked(null)` and leaves the UI untouched.
+- `login()` treats any response without `LoggedIn === true` as a failure, regardless of HTTP status. This is intentional: some backends return 200 with a failure flag.