wrolpi/wrolpi/bookmarks_api.py
lrnselfreliance 86d4bbab98
Some checks are pending
CodeQL / Analyze (push) Waiting to run
Controller Tests / controller-tests (push) Waiting to run
Jest Tests / jest-tests (push) Waiting to run
Bookmarks: a nav menu of user links, stored in bookmarks.yaml (#729)
* bookmarks: user bookmarks in the navigation bar, stored in bookmarks.yaml

A "Bookmarks" tab between Calculators and Flasher opens on hover or click and
lists the user's bookmarks, with directories as flyout submenus (Menu.Sub).
The mobile hamburger shows directories as labelled groups instead.  The tab
always shows, with an "Edit bookmarks" item, so the feature can be found
before any bookmark exists.

Bookmarks live in a new config-only bookmarks.yaml: a nested tree where a
node with `children` is a directory and a node with `url` is a bookmark.
Every node carries an integer id so the API can rename, move and delete
without relying on names.  A URL may be a path on this WROLPi, a port on this
host (`:8096/` or `http://:8096/`, resolved against whatever hostname the
browser used, so it works over LAN IP, mDNS and the hotspot alike), or an
absolute URL.  Each bookmark chooses whether to open in a new tab.

The editor at /more/bookmarks follows the playlist items table: numbered rows,
up/down/edit/delete, and inline "Add a bookmark" / "Add a directory" forms
with a Location picker.  Deleting a directory asks first, since its contents
go with it.  The menu and the editor are in the component gallery.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* bookmarks: mark More current when the editor is folded inside it; rem indents in the mobile menu

Found on the QA Pi at a width where Bookmarks overflows into More: the More
button carried no mark on /more/bookmarks, because the bookmarks link has no
`to` for isLinkActive to match.  isLinkActive now knows the bookmarks link owns
its editor page, and the Bookmarks tab uses the same rule.

The mobile menu's directory labels sat a few pixels left of the labels around
them: the indent was in em, and a Menu.Label is set smaller than a Menu.Item.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* bookmarks: parse URLs instead of matching a prefix; validate the whole tree on every write

The URL contract was checked by prefix on both sides, and a prefix is not a
form: `//evil.com` starts like a path and `:8096@evil.com` starts like a port,
and a browser takes both off this host.  A path is now a single leading slash
that resolves to this origin, a port form is an optional scheme, `:`, digits
and then only a path, query or fragment (no `@`, no backslash, no control
characters), and anything else must parse as http(s).  The same rules live in
wrolpi/bookmarks.py and BookmarksContext.js, with the same bypass strings in
both test suites.

The config's dataclass validator only saw that `bookmarks` was a list, so a
hand-edited file or the generic config API could store a `javascript:` URL
that the bookmarks API would refuse, and the nav rendered it.  The config now
validates the tree itself on every write and import: URL forms, exactly one of
url/children, unique integer ids, boolean new_tab, and no cycles (a YAML
anchor can build one).  An invalid file is not imported and, since it was never
successfully imported, is never overwritten.

On the page, a stored URL that does not resolve is rendered as text, never as
an href.  A refused add keeps what was typed instead of clearing the form, and
an edit whose move is refused still refreshes the nav (the rename was
committed) and keeps the modal open.  An IPv6 host is bracketed before a port.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* help: document Bookmarks

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-26 13:11:36 -06:00

86 lines
2.8 KiB
Python

from dataclasses import dataclass
from http import HTTPStatus
from typing import Optional
from sanic import Blueprint, Request, response
from sanic_ext import validate
from sanic_ext.extensions.openapi import openapi
from wrolpi.api_utils import json_response
from wrolpi.bookmarks import get_bookmarks_config
bookmarks_bp = Blueprint('Bookmarks', '/api/bookmarks')
@dataclass
class BookmarkRequest:
name: str
url: str
new_tab: bool = False
parent_id: Optional[int] = None
position: Optional[int] = None
@dataclass
class DirectoryRequest:
name: str
parent_id: Optional[int] = None
position: Optional[int] = None
@dataclass
class NodeUpdateRequest:
name: Optional[str] = None
url: Optional[str] = None
new_tab: Optional[bool] = None
@dataclass
class NodeMoveRequest:
parent_id: Optional[int] = None
position: Optional[int] = None
@bookmarks_bp.get('/')
@openapi.description('Get the bookmarks tree')
def get_bookmarks(_: Request):
return json_response(dict(bookmarks=get_bookmarks_config().bookmarks), HTTPStatus.OK)
@bookmarks_bp.post('/')
@openapi.description('Add a bookmark, optionally inside a directory')
@validate(BookmarkRequest)
async def post_bookmark(_: Request, body: BookmarkRequest):
node = get_bookmarks_config().add_bookmark(body.name, body.url, body.new_tab, body.parent_id, body.position)
return json_response(dict(bookmark=node), HTTPStatus.CREATED)
@bookmarks_bp.post('/directory')
@openapi.description('Add a bookmark directory, optionally inside another directory')
@validate(DirectoryRequest)
async def post_directory(_: Request, body: DirectoryRequest):
node = get_bookmarks_config().add_directory(body.name, body.parent_id, body.position)
return json_response(dict(bookmark=node), HTTPStatus.CREATED)
@bookmarks_bp.put('/<node_id:int>')
@openapi.description('Rename a bookmark or directory; change a bookmark URL or new-tab setting')
@validate(NodeUpdateRequest)
async def put_node(_: Request, node_id: int, body: NodeUpdateRequest):
node = get_bookmarks_config().update_node(node_id, body.name, body.url, body.new_tab)
return json_response(dict(bookmark=node), HTTPStatus.OK)
@bookmarks_bp.post('/<node_id:int>/move')
@openapi.description('Move a bookmark or directory into a directory (null parent = top level) at a position')
@validate(NodeMoveRequest)
async def post_move(_: Request, node_id: int, body: NodeMoveRequest):
node = get_bookmarks_config().move_node(node_id, body.parent_id, body.position)
return json_response(dict(bookmark=node), HTTPStatus.OK)
@bookmarks_bp.delete('/<node_id:int>')
@openapi.description('Delete a bookmark, or a directory and its contents')
async def delete_node(_: Request, node_id: int):
get_bookmarks_config().delete_node(node_id)
return response.empty(HTTPStatus.NO_CONTENT)