@spec after_cursor(term()) :: {:ok, Ecto.Query.dynamic_expr()} | :error

The condition of the files after a cursor/1, or :error when it is not one.

@spec aspects(scope(), PhoenixKit.Users.Auth.Scope.t() | nil) ::
  {:ok, %{required(section_id()) => binary()}} | {:error, error()}

The aspect ratio of every file of a library, for the styles that show whole photos: a map of section id to one byte per file, in the order the timeline shows them.

With these the browser knows the exact height of every month without fetching a single window, so the scrollbar and jump to month stay honest in those styles too. A byte is the logarithm of the ratio from 1:8 to 8:1 in 256 steps of 1.6%, which is finer than anyone can see in a crop and costs 260 KB for 200,000 files, once. assets/js/layouts.js reads it.

@spec base_filters() :: keyword()

The predicates every timeline query must carry, on phoenix_kit_files.

status == "active" keeps processing and failed rows out — they have no variants and would render as permanently grey tiles. The dimension predicate keeps ar from blowing up the layout.

edit_state is absent on purpose. A pending or failed edit occupies the same uuid and belongs in the grid.

@spec cursor(PhoenixKit.Modules.Storage.File.t()) :: String.t()

A place in the timeline's order, for paging. It holds the place itself rather than naming a file, so a page still follows on when the file it ended on has since been trashed or moved.

@spec default_library_uuid(PhoenixKit.Users.Auth.Scope.t() | nil) :: String.t() | nil

The library the timeline opens when the caller does not name one.

A user's default personal library when they have one, otherwise Media when they may see it (media_visible?/1), otherwise none.

@spec files_query(scope(), PhoenixKit.Users.Auth.Scope.t() | nil) ::
  {:ok, Ecto.Query.t()} | {:error, error()}

The query of what a timeline shows, for code that narrows it further (PhoenixKitPhotos.API). The library is checked for auth; each file of the answer still has to pass Libraries.can?/3.

@spec group_days([
  %{taken_on: Date.t(), count: non_neg_integer(), sum_aspect: number()}
]) :: [section()]

Folds per-day counts into month sections.

taken_on decides the month. The label is translated before it reaches the hook.

@spec ids_between(scope(), PhoenixKit.Users.Auth.Scope.t() | nil, keyword()) ::
  {:ok, [String.t()], boolean()} | {:error, error()}

The ids of positions from to to of the timeline, both included, at most limit. With :kind ("image" or "video") the positions are those of that kind only, and without from and to that is the whole library.

This is what a selection asks when a range runs through months the browser has not fetched.

@spec index(scope(), PhoenixKit.Users.Auth.Scope.t() | nil) ::
  {:ok, index()} | {:error, error()}

Monthly index for one library.

Live aggregation, grouped by taken_on. A photo taken late in the evening whose UTC instant falls on the next day stays in the month of taken_on.

@spec libraries(PhoenixKit.Users.Auth.Scope.t() | nil) :: [
  PhoenixKit.Modules.Storage.Library.t()
]

Libraries the scope may open in the timeline: the system library Media for someone who can manage it (media_visible?/1), then the user libraries they own or belong to.

Media does not require user libraries to be enabled. A personal library does.

@spec media_visible?(PhoenixKit.Users.Auth.Scope.t() | nil) :: boolean()

Whether the site's Media library is one of this scope's libraries.

It belongs to the site, not to a person: a system role or access to the media module (the rule for adding to it, Uploads.can_upload?/2). To anyone else it would be an empty library they cannot add to, since a user reads only their own uploads there.

@spec month_label(section_id()) :: String.t()

Already-translated month heading for a "2018-07" section id.

@spec position(scope(), String.t(), PhoenixKit.Users.Auth.Scope.t() | nil) ::
  {:ok, non_neg_integer()} | {:error, error()}

Where a photo is in the timeline: how many photos of the library come before it, in the order the timeline shows them (by day, then taken_at, then uuid). The browser opens the swipe viewer at that position, so an address that names a photo can open on it.

{:error, :not_found} for a file that is not in the library or that auth may not read.

@spec slide_limit() :: pos_integer()

Most files slides/6 returns at once.

@spec slides(
  scope(),
  window_id(),
  integer(),
  integer(),
  integer(),
  PhoenixKit.Users.Auth.Scope.t() | nil
) :: {:ok, [slide()]} | {:error, error()}

A slice of a window for the swipe viewer: count files (at most slide_limit/0) from position from of the day or day-slice day, in the order window/3 gives them, each with full-size URLs for a screen want pixels wide.

from + count may run past the end of a 500-item slice into the next one: the position is the same in the day, so the caller's index stays right.

@spec touches?(scope(), [String.t()]) :: boolean()

Whether a storage event about file_uuids can change what library scope shows.

Storage announces every file event to everyone, whichever library the file is in. This answers from where the files are kept, trashed ones included (a trashed file leaves the timeline but is still a row of its library). Files that no longer exist cannot be placed, so they count: someone's gone for good, and the timeline asks.

Read-authorized data for PhoenixKit's existing canvas viewer.

@spec window(scope(), window_id(), PhoenixKit.Users.Auth.Scope.t() | nil) ::
  {:ok, window()} | {:error, error()}

One day of items for a library, at most window_limit/0, ordered by taken_at.

Thumbnail and preview URLs come from Storage.variant_for/2 (a crop and an aspect-preserving size). The original is never used as a tile. Each URL is minted with Storage.authorized_url/4, which refuses a file the scope may not read.

@spec window_limit() :: pos_integer()

Maximum items returned in a single window; larger days are subdivided.